# Radio Button

> Source: https://design.nanatec.co.ke/components/radio-button/
> A button-styled radio option — interchangeable with `nana-radio` inside a `nana-radio-group`. Inside a horizontal group the buttons read as a segmented control. The group owns selection, keyboard roving and form association; on its own one still renders, selects and fires `nana-change`.

A button-styled radio option — interchangeable with `nana-radio` inside a
[`nana-radio-group`](/components/radio-group/). Inside a horizontal group the
buttons read as a segmented control. The group owns selection, keyboard roving
and form association; on its own one still renders, selects and fires
`nana-change`.

## Preview

```html
<nana-radio-group label="Billing period" orientation="horizontal" value="monthly">
  <nana-radio-button value="monthly">Monthly</nana-radio-button>
  <nana-radio-button value="yearly">Yearly</nana-radio-button>
  <nana-radio-button value="lifetime">Lifetime</nana-radio-button>
</nana-radio-group>
```

## Installation

```bash
npm install @nana-tec/ui-components
```

## Import

```js
import "@nana-tec/ui-components/radio-button";
```

Already registered if you imported `@nana-tec/ui-components/radio-group`.

## Basic usage

```html
<nana-radio-group label="Billing period" orientation="horizontal" value="monthly">
  <nana-radio-button value="monthly">Monthly</nana-radio-button>
  <nana-radio-button value="yearly">Yearly</nana-radio-button>
</nana-radio-group>
```

## The segmented control

`orientation="horizontal"` on the **group** is what makes a row of these read as
one segmented control. In a vertical group they stay as separate stacked
buttons — useful when the options are long, or when each needs its own
description.

```html
<nana-radio-group label="Vertical" orientation="vertical" value="a">
  <nana-radio-button value="a">First option</nana-radio-button>
  <nana-radio-button value="b">Second option</nana-radio-button>
</nana-radio-group>

<nana-radio-group label="Horizontal" orientation="horizontal" value="a">
  <nana-radio-button value="a">First</nana-radio-button>
  <nana-radio-button value="b">Second</nana-radio-button>
</nana-radio-group>
```

## Mixing flavours

`nana-radio` and `nana-radio-button` are interchangeable children of the same
group, so a form can use a circle where it needs a description and a button
where it does not.

```html
<nana-radio-group label="Delivery" orientation="vertical" value="standard">
  <nana-radio-button value="standard">Standard</nana-radio-button>
  <nana-radio value="express" label="Express" description="Next working day"></nana-radio>
</nana-radio-group>
```

## Size

`size` is `sm`, `md` (default) or `lg`. Set it on the group to size every child
at once, or on a single option to override it.

```html
<nana-radio-group label="Small" size="sm" orientation="horizontal" value="a">
  <nana-radio-button value="a">Small</nana-radio-button>
  <nana-radio-button value="b">Small</nana-radio-button>
</nana-radio-group>

<nana-radio-group label="Large" size="lg" orientation="horizontal" value="a">
  <nana-radio-button value="a">Large</nana-radio-button>
  <nana-radio-button value="b">Large</nana-radio-button>
</nana-radio-group>
```

## Prefix icons

The `prefix` slot takes a leading icon — a
[`nana-icon`](/components/icon/), or anything else.

```html
<nana-radio-group label="View" orientation="horizontal" value="list">
  <nana-radio-button value="list"><nana-icon slot="prefix" name="list"></nana-icon>List</nana-radio-button>
  <nana-radio-button value="grid"><nana-icon slot="prefix" name="grid_on"></nana-icon>Grid</nana-radio-button>
  <nana-radio-button value="board"><nana-icon slot="prefix" name="view_list"></nana-icon>Board</nana-radio-button>
</nana-radio-group>
```

## Checked, disabled and invalid

Outside a group, drive `checked` yourself. Inside one, the group sets it from
`value` — write `checked` and the group will overwrite it on the next render, so
leave it to the group there.

```html
<nana-radio-button value="a" checked>Selected</nana-radio-button>
<nana-radio-button value="b" disabled>Unavailable</nana-radio-button>
```

`invalid` is a styling hook the group sets when its `error` is non-empty; it
paints the border in the danger colour. Set it directly only outside a group.

## Keyboard

| Key | Does |
| --- | --- |
| `Space` `Enter` | Select this option |
| `↓` `→` `↑` `←` | Move and select — handled by the group |

Inside a group, the group's roving tabindex decides which option is tabbable and
the arrows do the moving, so this element only answers the activation keys. The
host delegates focus to its inner `<button>`, which is what lets that roving
tabindex land on the visible control.

## API

## Accessibility

- The host carries `role="radio"` with a live `aria-checked`, and
  `aria-disabled` when disabled.
- The visible control is a real `<button type="button">`, so it is reachable
  and activatable without the host's role doing the work.

## Related components

<ul class="related not-content">
  <li><a href="/components/radio-group/">Radio Group</a></li>
  <li><a href="/components/radio/">Radio</a></li>
  <li><a href="/components/button-group/">Button Group</a></li>
  <li><a href="/components/button/">Button</a></li>
  <li><a href="/components/icon/">Icon</a></li>
</ul>

## Storybook

See every state and prop interactively in Storybook: https://storybook.nanatec.co.ke/?path=/docs/components-radio-button--docs
