# Checkbox-Group

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

## Elements

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

## Overview

### What does the component do?
The checkbox group combines [checkboxes](https://digital.sbb.ch/en/design-system/lyne/components/checkbox/) (also [checkbox panels](https://digital.sbb.ch/en/design-system/lyne/components/checkbox-panel/) or [selection expansion panels](https://digital.sbb.ch/en/design-system/lyne/components/selection-expansion-panel/)) into one group. Several entries can be selected at the same time. It defines arrangement, name and states (e.g. required, disabled) for all entries.

### When should the component be used?
* Whenever checkboxes that belong together are used.
* For a single selection, use the [radio button group](https://digital.sbb.ch/en/design-system/lyne/components/radio-button-group/) instead.

### Rules.
* A checkbox group only combines checkboxes that belong to the same question. The group needs a clear label, also for screen readers (`aria-label`).
* For many or long options, checkboxes are arranged one below the other (`orientation="vertical"`). Side by side only for a few short options. `horizontalFrom` defines from which width they are placed side by side.
* All checkboxes in a group have the same size.
* If a selection is required and none is made, an error message is shown for the whole group.

## Implementation (web components)

The `<sbb-checkbox-group>` component is used as a container for a collection of either
[sbb-checkbox](https://lyne-elements.app.sbb.ch/?path=/docs/elements-checkbox--docs)s, [sbb-checkbox-panel](https://lyne-elements.app.sbb.ch/?path=/docs/elements-checkbox-panel--docs)s,
or [sbb-selection-expansion-panel](https://lyne-elements.app.sbb.ch/?path=/docs/elements-selection-expansion-panel--docs).

```html
<sbb-checkbox-group>
  <sbb-checkbox value="checkbox-1">Label 1</sbb-checkbox>
  <sbb-checkbox value="checkbox-2">Label 2</sbb-checkbox>
  <sbb-checkbox value="checkbox-3">Label 3</sbb-checkbox>
</sbb-checkbox-group>

<sbb-checkbox-group>
  <sbb-selection-expansion-panel>
    <sbb-checkbox-panel>
      Value
      <span slot="suffix">
        <sbb-icon></sbb-icon>
        <span class="sbb-text-xs sbb-text--bold">CHF</span>
        <span class="sbb-text-m sbb-text--bold">40.00</span>
      </span>
    </sbb-checkbox-panel>
  </sbb-selection-expansion-panel>
</sbb-checkbox-group>
```

### Slots

The content is projected in an unnamed slot.

The component can display one or more [sbb-error](https://lyne-elements.app.sbb.ch/?path=/docs/elements-form-field--docs) components
right below the `<sbb-checkbox-group>` using the `error` slot.

```html
<sbb-checkbox-group>
  <sbb-checkbox value="checkbox-1">Label 1</sbb-checkbox>
  <sbb-checkbox value="checkbox-2">Label 2</sbb-checkbox>
  <sbb-checkbox value="checkbox-3">Label 3</sbb-checkbox>
  <sbb-error slot="error">You must accept all the terms and conditions.</sbb-error>
</sbb-checkbox-group>
```

### States

It is possible to mark the entire group as disabled or required using the properties `disabled` and `required`.

```html
<!-- All the child sbb-checkbox will be marked as required. -->
<sbb-checkbox-group required> ... </sbb-checkbox-group>

<!-- All the child sbb-checkbox will be marked as disabled. -->
<sbb-checkbox-group disabled> ... </sbb-checkbox-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-checkbox-group orientation="vertical" horizontal-from="large"> ... </sbb-checkbox-group>
```

The component has a `size` property, which can be used to change the size
of all the inner `<sbb-checkbox>` or `<sbb-checkbox-panel>` elements. Available sizes are `xs`, `s` and `m`.

```html
<sbb-checkbox-group size="s"> ... </sbb-checkbox-group>
```

## API (web components)

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