# Radio-Button-Group

Komponente des SBB Design Systems Lyne.

- Paket: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Aufbau: ein Element
- Kategorien: Form
- Status: Gestaltungsrichtlinien vollständig

## Links

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

## Elemente

- `sbb-radio-button-group`: It can be used as a container for radio button elements.

## Übersicht

### Was macht die Komponente?
Die Radio-Button-Group fasst [Radiobuttons](https://digital.sbb.ch/de/design-system/lyne/components/radio-button/) (auch [Radio-Button-Panels](https://digital.sbb.ch/de/design-system/lyne/components/radio-button-panel/) oder [Selection-Expansion-Panels](https://digital.sbb.ch/de/design-system/lyne/components/selection-expansion-panel/)) zu einer Gruppe zusammen. Es kann nur ein Eintrag gleichzeitig ausgewählt sein. Sie legt Anordnung, Name und Zustände (z.B. Pflichtfeld, deaktiviert) für alle Einträge fest.

### Wann soll die Komponente eingesetzt werden?
* Immer, wenn Radiobuttons verwendet werden.
* Für mehrere Auswahlen gleichzeitig ist stattdessen die [Checkbox-Group](https://digital.sbb.ch/de/design-system/lyne/components/checkbox-group/) zu verwenden.

### Regeln.
* Eine Radio-Button-Group fasst nur Radiobuttons zusammen, die zur selben Frage gehören. Die Gruppe braucht eine verständliche Beschriftung, auch für Screenreader (`aria-label`).
* Die Radiobuttons stehen bei vielen oder langen Optionen untereinander (`orientation="vertical"`). Nebeneinander nur bei wenigen, kurzen Optionen. Mit `horizontalFrom` lässt sich festlegen, ab welcher Breite sie nebeneinander stehen.
* Alle Radiobuttons einer Gruppe haben dieselbe Grösse.
* Ist eine Auswahl erforderlich, wird bei fehlender Auswahl eine Fehlermeldung zur ganzen Gruppe angezeigt.

## Implementation (Web Components, Englisch)

The `<sbb-radio-button-group>` is a component which can be used as a wrapper for
a collection of either [sbb-radio-button](https://lyne-elements.app.sbb.ch/?path=/docs/elements-radio-button--docs)s, [sbb-radio-button-panel](https://lyne-elements.app.sbb.ch/?path=/docs/elements-radio-button-panel--docs)s,
or [sbb-selection-expansion-panel](https://lyne-elements.app.sbb.ch/?path=/docs/elements-selection-expansion-panel--docs)s.
Individual radio-buttons inside a radio-group will inherit the `name` of the group.

```html
<!-- The first option will be selected by default -->
<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 value="Value three">Option three</sbb-radio-button>
</sbb-radio-button-group>
```

Pressing a `<sbb-radio-button>` checks it and unchecks the previously selected one, if any.
They can also be controlled programmatically by setting the value property of the parent radio group to the value of the radio.

Please note that within a `<sbb-radio-button-group>`, only one `<sbb-radio-button>` can be selected at a time;
if you need to select more than one item, it is recommended to use the `<sbb-checkbox-group>` component.

### States

The radio group can have different states:

- can be completely disabled by setting the property `disabled`;
- can be required by setting the property `required`.

```html
<!-- All child radio buttons will be disabled -->
<sbb-radio-button-group value="Value one" aria-label="Radio group label" disabled>
  ...
</sbb-radio-button-group>

<!-- The radio group and all child radio buttons will be marked as required -->
<sbb-radio-button-group value="Value one" aria-label="Radio group label" required>
  ...
</sbb-radio-button-group>
```

In order to deselect a `<sbb-radio-button>` inside the `<sbb-radio-button-group>`,
you can use the `allowEmptySelection` property, which will be proxied to the inner `<sbb-radio-button>`
enabling their deselection (by default, a selected `<sbb-radio-button>` cannot be deselected).

```html
<sbb-radio-button-group allow-empty-selection> ... </sbb-radio-button-group>
```

### Style

The `orientation` property is used to set item orientation. Possible values are `horizontal` (default) and `vertical`.
The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` to
indicate the minimum breakpoint from which the orientation changes to `horizontal`.

```html
<sbb-radio-button-group orientation="vertical" horizontal-from="large">
  ...
</sbb-radio-button-group>
```

### Events

Consumers can listen to the native `change`/`input` event on the `<sbb-radio-button-group>` component
to intercept the selection's change; the current value can be read from `event.detail.value`.

### Accessibility

In order to ensure readability for screen-readers, please provide an `aria-label` attribute for the `<sbb-radio-button-group>`.

### Complex Values

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

```ts
const values = [
  { value: 'value1', name: 'Option 1' },
  { value: 'value2', name: 'Option 2' },
];
```

```html
<sbb-radio-button-group .value="${values[0]}" name="name">
  <sbb-radio-button .value="${values[0]}">Option 1</sbb-radio-button>
  <sbb-radio-button .value="${values[1]}">Option 2</sbb-radio-button>
</sbb-radio-button-group>
```

When using complex objects, it is possible to provide a custom `compareWith` function to control how values are matched:

```ts
const complexValues = [
  { id: 1, name: 'Option 1' },
  { id: 2, name: 'Option 2' },
  { id: 3, name: 'Option 3' },
];
```

```html
<sbb-radio-button-group
  .compareWith="${(v1, v2) => v1?.id === v2?.id}"
  .value="${complexValues[0]}"
>
  <sbb-radio-button .value="${complexValues[0]}">${complexValues[0].name}</sbb-radio-button>
  <sbb-radio-button .value="${complexValues[1]}">${complexValues[1].name}</sbb-radio-button>
  <sbb-radio-button .value="${complexValues[2]}">${complexValues[2].name}</sbb-radio-button>
</sbb-radio-button-group>
```

## API (Web Components, Englisch)

Vollständige API-Tabellen (Attribute, Events, Slots, CSS-Eigenschaften): https://digital.sbb.ch/de/design-system/lyne/components/radio-button-group/api.md