# xpl-radio

Radio buttons allow users to make selections or choices. Radios are always single select, and can also act as controls.

## Design Tokens

The radio component uses the following Apollo Foundation tokens:

| Token | Usage |
|-------|-------|
| `--xpl-background-surface-default` | Disabled checked state background; styled label background (resting/hover/focused) |
| `--xpl-background-action-disabled` | Disabled state background; disabled label background (styled variant) |
| `--xpl-background-surface-information` | Checked label background (styled variant) |
| `--xpl-border-strong` | Resting (unchecked) border color |
| `--xpl-border-hover` | Checked/hover/active border color; styled container hover/focus border |
| `--xpl-border-default` | Disabled state border color |
| `--xpl-border-focus` | Focus visible outline |
| `--xpl-border-radius-small` | Styled container corner radius (4px) |
| `--xpl-border-small` | Default border width (1px) |
| `--xpl-size-100` | Radio dimensions (16px) |

<!-- Auto Generated Below -->


## Properties

| Property        | Attribute        | Description                                                                                                                                                                                                                                                                                                                                                                                                                      | Type      | Default     |
| --------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ----------- |
| `checked`       | `checked`        | Whether the input is "on"                                                                                                                                                                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
| `description`   | `description`    | Description text for the field                                                                                                                                                                                                                                                                                                                                                                                                   | `string`  | `undefined` |
| `disabled`      | `disabled`       | Whether the input is disabled                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean` | `undefined` |
| `name`          | `name`           | The name attribute for the html input. (submitted in form as name/value pair)                                                                                                                                                                                                                                                                                                                                                    | `string`  | `undefined` |
| `required`      | `required`       | Whether the input is required                                                                                                                                                                                                                                                                                                                                                                                                    | `boolean` | `undefined` |
| `selectedValue` | `selected-value` | The currently selected value for the radio group this radio belongs to.  When set, the radio renders as checked when `selectedValue` equals its own `value` prop. Use this to drive radio-group selection from a single source of truth — e.g. Vue `v-model` on a shared `selectedValue` across every radio in a group, where each radio still declares its own `value`.  Falls back to the boolean `checked` prop when not set. | `string`  | `undefined` |
| `styled`        | `styled`         | Whether the input is contained in a box with a border and, in disabled state, a background                                                                                                                                                                                                                                                                                                                                       | `boolean` | `undefined` |
| `value`         | `value`          | The value attribute for the radio input. (submitted in form as name/value pair)                                                                                                                                                                                                                                                                                                                                                  | `string`  | `undefined` |


## Events

| Event         | Description                                                                                                                                             | Type                             |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `radioChange` | Event that emits the current value of the radio input  Returns the value of the radio input if a value is provided, otherwise returns the checked state | `CustomEvent<boolean \| string>` |


## Dependencies

### Used by

 - [xpl-choicelist](../xpl-choicelist)
 - [xpl-list-item](../xpl-list/xpl-list-item)

### Graph
```mermaid
graph TD;
  xpl-choicelist --> xpl-radio
  xpl-list-item --> xpl-radio
  style xpl-radio fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*