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

## Elements

- `sbb-checkbox-panel`: It displays a checkbox enhanced with selection panel 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?
The checkbox panel has the same function as the [checkbox](https://digital.sbb.ch/en/design-system/lyne/components/checkbox/). In addition, it can display subtexts, card badges or icons.

### When should the component be used?
* To select several independent options or to confirm consents (e.g. newsletter subscription).
* If the checkbox panel fits better into the layout than the normal checkbox.
* If further content (icons, texts, card badges) is required to describe the selection.
* If content of your choice is to be displayed below the checkbox panel. For technical implementation, see "[Selection-Expansion-Panel](https://digital.sbb.ch/en/design-system/lyne/components/selection-expansion-panel/)".

### Rules.
* Each checkbox panel is clearly labelled and names the option unambiguously.
* Several checkbox panels are combined in a [checkbox group](https://digital.sbb.ch/en/design-system/lyne/components/checkbox-group/), with a maximum of 5–7 options per group.
* A checkbox panel does not contain too much content, so that it stays readable and clear.
* If a checkbox panel has no visible text, it needs an `aria-label`.

## Implementation (web components)

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

### 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-checkbox-panel>
  <sbb-card-badge>%</sbb-card-badge>
  Label
  <span slot="subtext">Subtext</span>
  <span slot="suffix">Suffix</span>
</sbb-checkbox-panel>
```

### States

The component could be checked or not depending on the value of the `checked` attribute.

```html
<sbb-checkbox-panel value="example-value" checked>Checked state</sbb-checkbox-panel>
```

It has a third state too, which is set if the `indeterminate` property is true.
This is useful when multiple dependent checkbox-panels are used
(e.g., a parent which is checked only if all the children are checked, otherwise is in indeterminate state).
Clicking on a `<sbb-checkbox-panel>` in this state sets `checked` to `true` and `indeterminate` to false.

```html
<sbb-checkbox-panel value="indeterminate-checkbox-panel" indeterminate="true"
  >Indeterminate state</sbb-checkbox-panel
>
```

The component can be disabled by using the `disabled` property.

```html
<sbb-checkbox-panel value="disabled-checkbox" disabled="true">Disabled</sbb-checkbox-panel>
```

### Style

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

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

The component has three possible `size` values, named `xs`, `s` and `m`.
If the component is used within a group, the size is inherited from the group.

```html
<sbb-checkbox-panel size="s">Size</sbb-checkbox-panel>
```

### Events

Consumers can listen to the native `change` event on the `<sbb-checkbox-panel>` component to intercept the input's change;
the current state can be read from `event.target.checked`, while the value from `event.target.value`.

### Accessibility

The component provides the same accessibility features as the native checkbox.

Always provide an accessible label via `aria-label` for checkboxes without descriptive text content.
If you don't want the label to appear next to the checkbox, you can use `aria-label` to specify an appropriate label.

### Complex Values

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

```html
<sbb-checkbox-panel .value=${{value: 'value', name: 'name'}} name="name">Checkbox Panel</sbb-checkbox-panel>
```

## API (web components)

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