# Radio Component

The radio group component is designed for selecting one option from a set of choices.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/radio-group.js';
import 'mdui/components/radio.js';
```

Import the TypeScript type:

```ts
import type { RadioGroup } from 'mdui/components/radio-group.js';
import type { Radio } from 'mdui/components/radio.js';
```

Example:

```html
<mdui-radio-group value="chinese">
  <mdui-radio value="chinese">Chinese</mdui-radio>
  <mdui-radio value="english">English</mdui-radio>
</mdui-radio-group>
```

## Examples {#examples}

### Checked State {#example-checked}

The `value` property of the `<mdui-radio-group>` component corresponds to the `value` of the currently selected `<mdui-radio>` component. You can change the selected radio button by updating the `value` property of the `<mdui-radio-group>` component.

```html
<mdui-radio-group value="chinese">
  <mdui-radio value="chinese">Chinese</mdui-radio>
  <mdui-radio value="english">English</mdui-radio>
</mdui-radio-group>
```

The `<mdui-radio>` component can also be used independently. In this case, use the `checked` property to access and modify the checked state.

```html
<mdui-radio checked>Radio</mdui-radio>
```

### Disabled State {#example-disabled}

To disable the entire radio group, add the `disabled` attribute to the `<mdui-radio-group>` component.

```html
<mdui-radio-group disabled>
  <mdui-radio value="chinese">Chinese</mdui-radio>
  <mdui-radio value="english">English</mdui-radio>
</mdui-radio-group>
```

To disable a specific radio button, add the `disabled` attribute to the `<mdui-radio>` component.

```html
<mdui-radio-group>
  <mdui-radio value="chinese">Chinese</mdui-radio>
  <mdui-radio value="english" disabled>English</mdui-radio>
</mdui-radio-group>
```

### Icons {#example-icon}

You can set Material Icons for the unchecked and checked states of the radio button using the `unchecked-icon` and `checked-icon` attributes, respectively. Alternatively, you can use the `unchecked-icon` and `checked-icon` slots.

```html
<mdui-radio-group value="chinese">
  <mdui-radio
    unchecked-icon="check_box_outline_blank"
    checked-icon="lock"
    value="chinese"
  >Chinese</mdui-radio>
  <mdui-radio value="english">
    <mdui-icon slot="unchecked-icon" name="check_box_outline_blank"></mdui-icon>
    <mdui-icon slot="checked-icon" name="lock"></mdui-icon>
    English
  </mdui-radio>
</mdui-radio-group>
```

## mdui-radio-group API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the radio group.</p>
</td>
  </tr>
  <tr>
    <td>form</td>
    <td>form</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Associates the radio group with a <code>&lt;form&gt;</code> element. Set this to the <code>id</code> of a <code>&lt;form&gt;</code> in the same document. If omitted, the radio group uses its parent <code>&lt;form&gt;</code>, if any.</p>
<p>This lets the radio group work with any form in the document, not just the one it is nested in.</p>
</td>
  </tr>
  <tr>
    <td>name</td>
    <td>name</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>The name of the radio group, which is submitted with form data.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>The value of the selected radio button, which is submitted with form data.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>defaultValue</td>
    <td>false</td>
    <td>string</td>
    <td>''</td>
    <td><p>The default selected value. The radio group resets to this value when the form is reset. JavaScript only.</p>
</td>
  </tr>
  <tr>
    <td>required</td>
    <td>required</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Requires a radio selection when the form is submitted.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validity</td>
    <td>false</td>
    <td>ValidityState</td>
    <td></td>
    <td><p>A <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState" target="_blank" rel="noopener nofollow"><code>ValidityState</code></a> object that represents the element&#39;s validity states.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validationMessage</td>
    <td>false</td>
    <td>string</td>
    <td></td>
    <td><p>Validation message. Empty string when valid.</p>
</td>
  </tr>
</tbody>
</table>

### Methods

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>checkValidity(): boolean</td>
    <td><p>Checks the validity of the form field. If it is invalid, it triggers an <code>invalid</code> event and returns <code>false</code>. If valid, it returns <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>reportValidity(): boolean</td>
    <td><p>Checks the validity of the form field. If it is invalid, it triggers an <code>invalid</code> event, returns <code>false</code>, and displays a validation message. If valid, it returns <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>setCustomValidity(message: string): void</td>
    <td><p>Sets a custom error message. If the message is non-empty, the field is considered invalid.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>change</td>
    <td><p>Emitted when the selected value changes.</p>
</td>
  </tr>
  <tr>
    <td>input</td>
    <td><p>Emitted when the selected value changes.</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>Emitted when the form control&#39;s validity is checked and it does not meet the constraints.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p><code>&lt;mdui-radio&gt;</code> elements.</p>
</td>
  </tr>
</tbody>
</table>

## mdui-radio API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>Specifies the value of the radio.</p>
</td>
  </tr>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the radio.</p>
</td>
  </tr>
  <tr>
    <td>checked</td>
    <td>checked</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Sets the radio to the checked state.</p>
</td>
  </tr>
  <tr>
    <td>unchecked-icon</td>
    <td>uncheckedIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Specifies the Material Icons name for the unchecked state. Alternatively, use <code>slot=&quot;unchecked-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>checked-icon</td>
    <td>checkedIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Specifies the Material Icons name for the checked state. Alternatively, use <code>slot=&quot;checked-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Whether the element is focused when the page loads.</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>The element&#39;s tab order when navigating with the Tab key.</p>
</td>
  </tr>
</tbody>
</table>

### Methods

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>click(): void</td>
    <td><p>Simulates a mouse click on the element.</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Sets focus on the element. An optional object parameter may include a <code>preventScroll</code> property. If <code>preventScroll</code> is set to <code>true</code>, the page will not scroll to bring the focused element into view.</p>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Removes focus from the element.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Emitted when the radio gains focus.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Emitted when the radio loses focus.</p>
</td>
  </tr>
  <tr>
    <td>change</td>
    <td><p>Emitted when the radio is selected.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Text content.</p>
</td>
  </tr>
  <tr>
    <td>unchecked-icon</td>
    <td><p>Icon for the unchecked state.</p>
</td>
  </tr>
  <tr>
    <td>checked-icon</td>
    <td><p>Icon for the checked state.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>control</td>
    <td><p>Container for the left icon.</p>
</td>
  </tr>
  <tr>
    <td>unchecked-icon</td>
    <td><p>Icon for the unchecked state.</p>
</td>
  </tr>
  <tr>
    <td>checked-icon</td>
    <td><p>Icon for the checked state.</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td><p>Text content.</p>
</td>
  </tr>
</tbody>
</table>