# Radio

- Entry point: `@koobiq/components/radio`
- NgModule: `KbqRadioModule`
- API: https://koobiq.io/api/radio.md
- Component tokens: https://koobiq.io/tokens/radio.md
- Page: https://koobiq.io/en/components/radio/overview

Radio buttons allow users to select from a set of mutually exclusive, related options.

## States

### Size

[**Example: Radio size** (`radio-overview`)](https://koobiq.io/examples/radio-overview.md)

### Style

[**Example: Radio style** (`radio-style`)](https://koobiq.io/examples/radio-style.md)

### Content

[**Example: Radio content** (`radio-content`)](https://koobiq.io/examples/radio-content.md)

## Usage examples

### Radio Group

[**Example: Radio group** (`radio-group`)](https://koobiq.io/examples/radio-group.md)

### Multiline

[**Example: Radio multiline example** (`radio-multiline`)](https://koobiq.io/examples/radio-multiline.md)

### Validation

To show a validation error, bind the group to a form control, apply `required` or `Validators.required`, and put the error text in a `kbq-error` inside the group.

To show the error at another moment, pass a matcher to the `errorStateMatcher` input: the example below shows the error only after the form is submitted. The matchers are described in the [Validation guide](https://koobiq.io/en/other/validation.md).

[**Example: Radio validation** (`radio-validation`)](https://koobiq.io/examples/radio-validation.md)

## Keyboard interaction

The component installs no key handlers of its own. The options are real `<input type="radio">`
elements sharing a `name`, so the browser supplies the whole interaction:

- A group is a **single** tab stop. `Tab` enters it at the checked option — or at the first enabled
  one when nothing is checked — and the next `Tab` leaves the group entirely.
- The arrow keys move between options **and select as they move**, so a group cannot be traversed
  without changing its value. Disabled options are skipped.
- `Space` selects the focused option.

Grouping follows `name` rather than the markup: buttons sharing a name are one tab stop even when
they sit in different containers, and a button used outside a group is named uniquely to itself and
is therefore its own tab stop.

## Accessibility

A `kbq-radio-group` is announced as a `radiogroup`, which does not take its name from the options
inside it. Point it at the visible group label instead — write `aria-labelledby` (or `aria-label`)
directly on the element, the way you would on any other host:

```html
<div id="delivery-label" class="kbq-form__label">Delivery</div>
<kbq-radio-group aria-labelledby="delivery-label">
    <kbq-radio-button [value]="'pickup'">Pickup</kbq-radio-button>
    <kbq-radio-button [value]="'courier'">Courier</kbq-radio-button>
</kbq-radio-group>
```

A `kbq-hint` projected into a button is exposed as its description, not as part of its name, so an
option is announced by its own text and the caption is left for assistive technology to defer.

`[required]` on the group reaches the `radiogroup` as `aria-required`, and a group colored with the
error palette or in the error state reaches it as `aria-invalid`. The error and the hint of the group are announced as its description, together with an `aria-describedby` you set on the
group yourself.

`focus()` on a button — or on the group, which forwards to the checked option — accepts a
`FocusOrigin`. Pass `'keyboard'` when you move focus in response to a keyboard action, so the focus
ring is visible; the default `'program'` moves focus without one.

## Name and native forms

Every group generates a unique `name`, and its buttons inherit it, so nothing has to be named by
hand. A button used outside a group falls back to an id unique to itself and is therefore
independent of every other ungrouped radio in the application.

Name the group explicitly when it has to participate in a native `<form>` submission: that name is
the field name in the payload, and a generated one changes between application loads. The button's
`value` is submitted as a string, so only string-like values round-trip.

## Recommendations

- By default, it is recommended to use up to 7 options in a Radio Group.
- Use [Button Toggle](https://koobiq.io/en/components/button-toggle.md) for short options when there is sufficient horizontal space.
- If more than 7 options need to be displayed, it is better to use [Select](https://koobiq.io/en/components/select.md).
- If the selection involves two values and can be classified as boolean, use [Toggle](https://koobiq.io/en/components/toggle.md). Toggle applies changes instantly, without additional data saving.
