---
title: 'Checkbox Group: Use Cases'
parts:
  - Checkbox Group
  - Use Cases
eleventyNavigation:
  key: 'Checkbox Group: Use Cases'
  order: 20
  parent: Checkbox Group
  title: Use Cases
---

# Checkbox Group: Use Cases

```js script
import { html } from '@mdjs/mdjs-preview';
import '@lion/ui/define/lion-checkbox-group.js';
import '@lion/ui/define/lion-checkbox-indeterminate.js';
import '@lion/ui/define/lion-checkbox.js';
```

## Model value

The `modelValue` of a `lion-checkbox-group` is an array containing the `choiceValues` of the `lion-checkbox` elements that have been checked.

Given the scientists example above, say that we were to select the first and last options
(Archimedes & Marie Curie).

Then the `modelValue` of the `lion-checkbox-group` will look as follows:

```js
const groupElement = [parent].querySelector('lion-checkbox-group');
groupElement.modelValue;
  => ["Archimedes", "Marie Curie"];
```

## The `name` attribute

The `name` attribute of a `lion-checkbox-group` automatically gets assigned to its `lion-checkbox` children. You can also specify names for the `lion-checkbox` elements, but if this name is different from the name assigned to `lion-checkbox-group`, then an exception will be thrown.

Our recommendation would be to set the `name` attribute only on the `lion-checkbox-group` and not on the `lion-checkbox` elements.

## Example

```html
<lion-checkbox-group name="scientists[]" label="Favorite scientists">
  <lion-checkbox label="Archimedes" .choiceValue="${'Archimedes'}"></lion-checkbox>
  <lion-checkbox label="Francis Bacon" .choiceValue="${'Francis Bacon'}"></lion-checkbox>
  <lion-checkbox label="Marie Curie" .choiceValue="${'Marie Curie'}"></lion-checkbox>
</lion-checkbox-group>
```

## Pre-select

You can pre-select options by targeting the `modelValue` object of the option and setting the `checked` property to `true`.

```html preview-story
<lion-checkbox-group name="scientists" label="Favorite scientists">
  <lion-checkbox label="Archimedes" .choiceValue="${'Archimedes'}"></lion-checkbox>
  <lion-checkbox label="Francis Bacon" .choiceValue="${'Francis Bacon'}" checked></lion-checkbox>
  <lion-checkbox label="Marie Curie" .choiceValue="${'Marie Curie'}"></lion-checkbox>
</lion-checkbox-group>
```

## Disabled

You can disable the entire group by setting the `disabled` attribute on the `<lion-checkbox-group>`.

```html preview-story
<lion-checkbox-group name="scientists[]" label="Favorite scientists" disabled>
  <lion-checkbox label="Archimedes" .choiceValue="${'Archimedes'}"></lion-checkbox>
  <lion-checkbox label="Francis Bacon" .choiceValue="${'Francis Bacon'}"></lion-checkbox>
  <lion-checkbox label="Marie Curie" .choiceValue="${'Marie Curie'}"></lion-checkbox>
</lion-checkbox-group>
```

## Label

You can use `slot="label"` instead of the `label` attribute for defining more complex labels, such as containing screen reader only text or an anchor.

```html preview-story
<lion-checkbox-group name="scientists[]" label="Favorite scientists">
  <lion-checkbox .choiceValue="${'Archimedes'}">
    <label slot="label"><strong>Archimedes</strong></label>
  </lion-checkbox>
  <lion-checkbox .choiceValue="${'Francis Bacon'}">
    <label slot="label"><strong>Francis Bacon</strong></label>
  </lion-checkbox>
  <lion-checkbox .choiceValue="${'Marie Curie'}">
    <label slot="label"><strong>Marie Curie</strong></label>
  </lion-checkbox>
</lion-checkbox-group>
```

## Help text

You can add help text on each checkbox with `help-text` attribute on the `<lion-checkbox>`.

```html preview-story
<lion-checkbox-group name="scientists[]" label="Favorite scientists">
  <lion-checkbox
    label="Archimedes"
    .choiceValue="${'Archimedes'}"
    help-text="Archimedes of Syracuse was a Greek mathematician, physicist, engineer, inventor, and astronomer"
  ></lion-checkbox>
  <lion-checkbox
    label="Francis Bacon"
    .choiceValue="${'Francis Bacon'}"
    help-text="Francis Bacon, 1st Viscount St Alban also known as Lord Verulam, was an English philosopher and statesman who served as Attorney General and as Lord Chancellor of England"
  ></lion-checkbox>
  <lion-checkbox
    label="Marie Curie"
    .choiceValue="${'Marie Curie'}"
    help-text="Marie Skłodowska Curie born Maria Salomea Skłodowska, was a Polish and naturalized-French physicist and chemist who conducted pioneering research on radioactivity"
  ></lion-checkbox>
</lion-checkbox-group>
```

## Event

You can listen to the `model-value-changed` event whenever the value of the checkbox group is changed.

```js preview-story
export const event = ({ shadowRoot }) => html`
  <lion-checkbox-group
    name="scientists[]"
    label="Favorite scientists"
    @model-value-changed=${ev =>
      (ev.target.parentElement.querySelector('#selectedDinosaur').innerText = JSON.stringify(
        ev.target.modelValue,
        null,
        4,
      ))}
  >
    <lion-checkbox label="Archimedes" .choiceValue="${'Archimedes'}"></lion-checkbox>
    <lion-checkbox label="Francis Bacon" .choiceValue="${'Francis Bacon'}"></lion-checkbox>
    <lion-checkbox label="Marie Curie" .choiceValue="${'Marie Curie'}"></lion-checkbox>
  </lion-checkbox-group>
  <br />
  <span>Selected scientists: <strong id="selectedDinosaur">N/A</strong></span>
`;
```

## Indeterminate

A `checkbox-indeterminate`'s value is neither true nor false, but is instead indeterminate, meaning that its state cannot be determined or stated in pure binary terms, based on it's `checkbox` children.

```html preview-story
<lion-checkbox-group name="scientists[]" label="Favorite scientists">
  <lion-checkbox-indeterminate label="Old Greek scientists">
    <lion-checkbox label="Archimedes" .choiceValue="${'Archimedes'}"></lion-checkbox>
    <lion-checkbox label="Plato" .choiceValue="${'Plato'}"></lion-checkbox>
    <lion-checkbox label="Pythagoras" .choiceValue="${'Pythagoras'}"></lion-checkbox>
  </lion-checkbox-indeterminate>
  <lion-checkbox-indeterminate label="17th Century scientists">
    <lion-checkbox label="Isaac Newton" .choiceValue="${'Isaac Newton'}"></lion-checkbox>
    <lion-checkbox label="Galileo Galilei" .choiceValue="${'Galileo Galilei'}"></lion-checkbox>
  </lion-checkbox-indeterminate>
</lion-checkbox-group>
```

The `checkbox-indeterminate` can have another `checkbox-indeterminate` as a child.

```html preview-story
<lion-checkbox-group name="scientists[]" label="Favorite scientists">
  <lion-checkbox-indeterminate label="Scientists">
    <lion-checkbox label="Isaac Newton" .choiceValue="${'Isaac Newton'}"></lion-checkbox>
    <lion-checkbox label="Galileo Galilei" .choiceValue="${'Galileo Galilei'}"></lion-checkbox>
    <lion-checkbox-indeterminate label="Old Greek scientists">
      <lion-checkbox label="Archimedes" .choiceValue="${'Archimedes'}"></lion-checkbox>
      <lion-checkbox label="Plato" .choiceValue="${'Plato'}"></lion-checkbox>
      <lion-checkbox label="Pythagoras" .choiceValue="${'Pythagoras'}"></lion-checkbox>
    </lion-checkbox-indeterminate>
  </lion-checkbox-indeterminate>
</lion-checkbox-group>
```

You can also use `mixed-state` attribute so your indeterminate checkbox toggles through three states (indeterminate, checked, unchecked), where for indeterminate state the old children states are restored when you toggle back into this.

```html preview-story
<lion-checkbox-group name="scientists[]" label="Favorite scientists">
  <lion-checkbox-indeterminate mixed-state label="Scientists">
    <lion-checkbox label="Isaac Newton" .choiceValue="${'Isaac Newton'}"></lion-checkbox>
    <lion-checkbox label="Galileo Galilei" .choiceValue="${'Galileo Galilei'}"></lion-checkbox>
    <lion-checkbox-indeterminate mixed-state label="Old Greek scientists">
      <lion-checkbox label="Archimedes" .choiceValue="${'Archimedes'}"></lion-checkbox>
      <lion-checkbox label="Plato" .choiceValue="${'Plato'}"></lion-checkbox>
      <lion-checkbox label="Pythagoras" .choiceValue="${'Pythagoras'}"></lion-checkbox>
    </lion-checkbox-indeterminate>
  </lion-checkbox-indeterminate>
</lion-checkbox-group>
```
