# Radio


## Examples

### Default

```html
<m-radio
      value=${args.value}
      name=${args.name ?? ""}
      ?checked=${args.checked}
      ?disabled=${args.disabled}
      ?readonly=${args.readonly}
      ?required=${args.required}
      ?labelHidden=${args.labelHidden}
      label=${args.label || ""}
      hint=${args.hint || ""}
      description=${args.description || ""}
      error=${args.error || ""}
      @input=${args.oninput}
      @change=${args.onchange}
    ></m-radio>
```

### RadioGroup

```html
<m-stack direction="vertical" spacing="m">
      <m-radio name="group" label="Option 1" value="1"></m-radio>
      <m-radio name="group" label="Option 2" value="2"></m-radio>
      <m-radio name="group" label="Option 3" value="3"></m-radio>
    </m-stack>
```

### States

```html
<m-stack direction="vertical" spacing="m">
      <m-radio label="Default radio"></m-radio>
      <m-radio label="Checked radio" checked></m-radio>
      <m-radio label="Disabled radio" disabled></m-radio>
      <m-radio label="Disabled checked radio" disabled checked></m-radio>
      <m-radio label="Readonly radio" readonly></m-radio>
      <m-radio label="Readonly checked radio" readonly checked></m-radio>
      <m-radio label="Required radio" required></m-radio>
      <m-radio label="Required checked radio" required checked></m-radio>
    </m-stack>
```

### WithHint

```html
<m-radio
      label="Radio with hint"
      hint="This is a helpful hint text"
    ></m-radio>
```

### WithDescription

```html
<m-radio
      label="Radio with description"
      description="This is a helpful description text"
    ></m-radio>
```

### WithError

```html
<m-stack direction="vertical" spacing="m">
        <m-radio label="Checked radio with error" checked error="This field is required"></m-radio>
        <m-radio label="Unchecked radio with error">
        <span slot="error">This field is required</span>
        </m-radio>
    </m-stack>
```

### WithCustomContent

```html
<m-radio>
      <span slot="label">Custom <strong>formatted</strong> label</span>
      <span slot="hint">Custom <em>formatted</em> hint</span>
      <span slot="error">Custom <em>formatted</em> error</span>
    </m-radio>
```

## Usage

**Use a Radio Button to:**
- Allow users to select one option from a list when multiple choices exist.
- Present mutually exclusive options, where selecting one automatically deselects others.
- Indicate a required selection, ensuring that users make a decision before proceeding.

**Do not use a Radio Button to:**

- Allow multiple selections (use checkboxes instead).
- Toggle a single setting on or off (use a checkbox or toggle switch instead).
- Display a long list of options (consider a dropdown for better space management).

## Other Considerations

- Ensure each radio button descriptive labels that clearly communicate the choice (e.g., “Full-time”, “Part-time”).
- Avoid using vague options like “Yes” and “No” unless the context is clear.
- Default to the most common or recommended option when appropriate.
- Visually group related options under a heading or a question to provide context.
- Ensure that all radio buttons in a group are logically ordered for a smooth user experience.

## Design Rationale
- Mutual exclusivity ensures users can only select one option, preventing conflicting choices.
- Immediate feedback provides clarity, as selecting one option automatically deselects the others.
- Ease of use makes radio buttons a familiar and effective choice for form inputs.
- Consistency with accessibility guidelines ensures that all users, including those using assistive technologies, can easily interact with radio buttons.