# Option

Component of the SBB design system Lyne.

- Package: `@sbb-esta/lyne-elements` (Angular: `@sbb-esta/lyne-angular`)
- Structure: several elements that can be used on their own
- Categories: Form
- Status: Design guidelines complete

## Links

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

## Elements

- `sbb-option`, several can be combined with `sbb-optgroup`: It displays on option item which can be used in `sbb-select` or `sbb-autocomplete`.
- `sbb-option-hint`: Display a textual hint inside a `sbb-autocomplete` or a `sbb-select`.

## Overview

### What does the component do?
The option is a selectable entry in an [autocomplete](https://digital.sbb.ch/en/design-system/lyne/components/autocomplete/) or [select](https://digital.sbb.ch/en/design-system/lyne/components/select/) component. Options can be grouped with an optgroup. In autocomplete, a hint (option hint) can be shown additionally.

### When should the component be used?
* Only within the autocomplete or select component.

### Rules.
* Each option has a short, clear label and is clearly distinguishable from the others.
* Related options are grouped with an optgroup. If the group is disabled, all its options are disabled.
* An icon is optional.
* When searching in autocomplete, the matching text is highlighted in bold.
* The option hint (e.g. "No results") is only possible in autocomplete. Screen readers read it only as plain text; mark it as a live region if needed.

## Implementation (web components)

The `<sbb-option>` is a component which can be used to display items in components like
[sbb-autocomplete](https://lyne-elements.app.sbb.ch/?path=/docs/elements-autocomplete--docs) or a [sbb-select](https://lyne-elements.app.sbb.ch/?path=/docs/elements-select--docs).

It is based on the native `option` element. As such, it can be labeled via its text content.
The component can optionally display an `<sbb-icon>` at the component start using the `iconName` property
or via custom content using the `icon` slot.

```html
<sbb-option>Option label</sbb-option>

<sbb-option icon-name="info">Option label</sbb-option>
```

Like the native `option`, the component has a `value` property.

The state of the `<sbb-option>` can be configured via the `selected` and `disabled` attributes/properties.
When disabled, the selection via click is prevented.
If the `<sbb-option>` is nested in an `<sbb-optgroup>` component, it inherits the `disabled` state from
the parent.

```html
<sbb-option value="value" selected>Option label</sbb-option>

<sbb-option value="value" disabled>Option label</sbb-option>
```

### Events

Consumers can listen to the `optionselected` event on the `<sbb-option>` component to react to the selected
value. The event is triggered if the element has been selected by user interaction. Alternatively,
the `optionselectionchange` event can be listened to, which is triggered if the element has either been
selected or deselected.

### Style

If the label slot contains only a **text node**, it is possible to search for text in the `<sbb-option>`
using the `highlight` method, passing the desired text; if the text is present it will be highlighted
in bold.

```html
<!-- Supported scenario -->
<sbb-option> Highlightable caption</sbb-option>

<!-- Not supported scenarios -->
<sbb-option>
  <span>Not highlightable caption</span>
</sbb-option>

<sbb-option>
  <img src="..." />
  Highlightable caption
</sbb-option>
```

### Complex Values

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

```ts
const option = document.querySelector('sbb-option');
option.value = { value: 'value', name: 'name' };
option.textContent = 'Example';
```

### sbb-optgroup

The `<sbb-optgroup>` is a component used to group more `<sbb-option>` within an
[sbb-autocomplete](https://lyne-elements.app.sbb.ch/?path=/docs/elements-autocomplete--docs) or an
[sbb-select](https://lyne-elements.app.sbb.ch/?path=/docs/elements-select--docs) component.

The component has a `label` property as the name of the group.

```html
<sbb-optgroup label="Group">
  <sbb-option value="1" selected>1</sbb-option>
  <sbb-option value="2">2</sbb-option>
  <sbb-option value="3">3</sbb-option>
</sbb-optgroup>
```

#### States

The component has a `disabled` property which sets all the `<sbb-option>` in the group as disabled.

```html
<sbb-optgroup label="Disabled group" disabled>
  <sbb-option value="A">A</sbb-option>
  <sbb-option value="B">B</sbb-option>
  <sbb-option value="C">C</sbb-option>
</sbb-optgroup>
```

### sbb-option-hint

The `<sbb-option-hint>` is an optional component used to show a hint message within an
[sbb-autocomplete](https://lyne-elements.app.sbb.ch/?path=/docs/elements-autocomplete--docs).

```html
<sbb-autocomplete>
  <sbb-option value="1"> Option 1 </sbb-option>
  ...
  <sbb-divider></sbb-divider>
  <sbb-option-hint>42 more hits</sbb-option-hint>
</sbb-autocomplete>
```

#### Style

The `<sbb-option-hint>` has a `negative` property which will be automatically inherited from the parent `<sbb-autocomplete>`.

```html
<sbb-autocomplete>
  <sbb-option value="1">Option 1</sbb-option>
  ...
  <sbb-option-hint>42 more hits</sbb-option-hint>
</sbb-autocomplete>
```

### A11y

By default, the `<sbb-option-hint>` is treated as a simple text from screen readers, and it is not easily accessible by screen reader users.

If deemed necessary, the `<sbb-option-hint>` can be marked with the [aria-live](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-live) attribute.

## API (web components)

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