# Radio-Button

Component of the SBB design system Lyne.

- Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Structure: one element
- Categories: Form
- Status: Design guidelines complete

## Links

- Page on digital.sbb.ch: https://digital.sbb.ch/en/design-system/lyne/components/radio-button/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-radio-button--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/radio-button/overview (API: https://lyne-angular.app.sbb.ch/angular/components/radio-button/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=7491-48
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/radio-button

## Elements

- `sbb-radio-button`: It displays a radio button enhanced with the SBB Design.

## Related components

- Similar: [Checkbox](https://digital.sbb.ch/en/design-system/lyne/components/checkbox/index.md), [Radio-Button-Panel](https://digital.sbb.ch/en/design-system/lyne/components/radio-button-panel/index.md)

## Overview

### What does the component do?
A radio button allows users to make a selection from a group of options, whereby only one option can be selected at a time.

### When should the component be used?
* When users should make a selection from a limited number of options.
* When only one option may be selected from several possible options.

### Rules.
* Radio buttons should be used in groups ([radio-button-group](https://digital.sbb.ch/en/design-system/lyne/components/radio-button-group/)) to provide a clear choice.
* Each option within a radio-button-group should be clearly labelled and easy to understand.
* Avoid placing too many options in a radio button group to ensure clarity and to make selection easier.

## Implementation (web components)

The `<sbb-radio-button>` component provides the same functionality as a native `<input type="radio"/>` enhanced with the SBB Design.

Radio-buttons should typically be placed inside a [sbb-radio-button-group](https://lyne-elements.app.sbb.ch/?path=/docs/elements-radio-button-group--docs) component
in order to display a radio input within a group. Individual radio-buttons inside a radio-group will inherit the `name` of the group.

```html
<sbb-radio-button-group name="radio-group" value="Value one" aria-label="Radio group label">
  <sbb-radio-button value="Value one">Option one</sbb-radio-button>
  <sbb-radio-button value="Value two">Option two</sbb-radio-button>
</sbb-radio-button-group>
```

In cases where that's not possible, you can define a group of radios using the same `name` property

```html
<sbb-radio-button name="radio-group" value="Value one" checked>Option one</sbb-radio-button>
<sbb-radio-button name="radio-group" value="Value two">Option two</sbb-radio-button>
```

### States

It is possible to display the component in `disabled` or `checked` state by using the self-named properties.

The component has a `required` property, which can be useful
for setting a custom [sbb-error](https://lyne-elements.app.sbb.ch/?path=/docs/elements-form-field--docs) message
within a [sbb-form-field](https://lyne-elements.app.sbb.ch/?path=/docs/elements-form-field--docs).

The `allowEmptySelection` property allows user to deselect the component.

```html
<sbb-radio-button value="One" checked>Option one</sbb-radio-button>

<sbb-radio-button value="Two" disabled>Option two</sbb-radio-button>

<sbb-radio-button value="Three" required>Option three</sbb-radio-button>

<sbb-radio-button value="Four" allowEmptySelection>Option four</sbb-radio-button>
```

### Style

The component has three different sizes, which can be changed using the `size` property (`xs`, `s` or `m`).
If used inside a `<sbb-radio-button-group>`, the `size` will be inherited from it.

```html
<sbb-radio-button value="small" size="s">Size</sbb-radio-button>
```

The component's label can be displayed in bold using the `sbb-text--bold` class on a wrapper tag:

```html
<sbb-radio-button value="bold">
  <span class="sbb-text--bold">Bold label</span>
</sbb-radio-button>
```

### Complex Values

This component supports any types of values, including complex objects.
The type can be specified using the generic type parameter `T` of `SbbRadioButton<T>`.

```html
<sbb-radio-button .value=${{value: 'value', name: 'name'}} name="name">Option</sbb-radio-button>
```

## API (web components)

Full API tables (attributes, events, slots, CSS properties): https://digital.sbb.ch/en/design-system/lyne/components/radio-button/api.md