# Radio-Button-Panel

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-panel/
- Storybook: https://lyne-elements.app.sbb.ch/?path=/docs/elements-radio-button-panel--docs
- Angular (`@sbb-esta/lyne-angular`): https://lyne-angular.app.sbb.ch/angular/components/radio-button-panel/overview (API: https://lyne-angular.app.sbb.ch/angular/components/radio-button-panel/api)
- Figma: https://www.figma.com/design/mWknI2rC5DJmOgRO61WKai/Lyne-Components?node-id=31104-609908
- GitHub: https://github.com/sbb-design-systems/lyne-components/tree/v5.12.0/src/elements/radio-button-panel

## Elements

- `sbb-radio-button-panel`: It displays a radio button enhanced with the panel design.

## Related components

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

## Overview

### What does the component do?
The radio button panel has the same function as the [radio button](https://digital.sbb.ch/en/design-system/lyne/components/radio-button/). In addition, it offers space for a subtext, card badge, icon or suffix.

### When should the component be used?
* When users should select exactly one option from a limited number of options.
* When the normal radio button is not enough to describe the option, e.g. because of a subtext, icon or card badge.
* When the panel fits better into the layout than the normal radio button.
* When content of your choice should be displayed below the option: combine the radio button panel with the [selection expansion panel](https://digital.sbb.ch/en/design-system/lyne/components/selection-expansion-panel/).
* When an option has its own action: combine the radio button panel with the [selection action panel](https://digital.sbb.ch/en/design-system/lyne/components/selection-action-panel/).

### Rules.
* Radio button panels are used in a [radio button group](https://digital.sbb.ch/en/design-system/lyne/components/radio-button-group/).
* Each option is clearly labelled and easy to understand.
* Avoid too many options in a group.
* Avoid too much content per panel to keep it readable.

## Implementation (web components)

The `<sbb-radio-button-panel>` component provides the same functionality as a native `<input type="radio"/>` enhanced with the selection panel design and functionalities.

Radio-buttons should typically be placed inside a [sbb-radio-button-group](https://lyne-elements.app.sbb.ch/?path=/docs/elements-radio-button--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-panel value="Value one">Option one</sbb-radio-button-panel>
  <sbb-radio-button-panel value="Value two">Option two</sbb-radio-button-panel>
</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-panel name="radio-group" value="Value one">Option one</sbb-radio-button-panel>
<sbb-radio-button-panel name="radio-group" value="Value two">Option two</sbb-radio-button-panel>
```

### Slots

It is possible to provide a label via an unnamed slot;
additionally the slots named `subtext` can be used to provide a subtext and
the slot named `suffix` can be used to provide suffix items.
If you use a `<sbb-card-badge>`, the slot `badge` is automatically assigned.

```html
<sbb-radio-button-panel>
  <sbb-card-badge>%</sbb-card-badge>
  Label
  <span slot="subtext">Subtext</span>
  <span slot="suffix">Suffix</span>
</sbb-radio-button-panel>
```

### States

It is possible to display the component in `disabled` or `checked` state by using the self-named properties.
The `allowEmptySelection` property allows user to deselect the component.

```html
<sbb-radio-button-panel value="One" checked>Option one</sbb-radio-button-panel>
<sbb-radio-button-panel value="Two" disabled>Option two</sbb-radio-button-panel>
<sbb-radio-button-panel value="Three" allowEmptySelection>Option three</sbb-radio-button-panel>
```

### 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-panel size="s">Size</sbb-radio-button-panel>
```

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

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

### Complex Values

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

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

## API (web components)

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