Checkbox Group: Use Cases

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:

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

<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.

<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>.

<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.

<lion-checkbox-group name="scientists[]" label="Favorite scientists">
  <lion-checkbox .choiceValue="${'Archimedes'}">
    <label slot="label"
      ><a href="https://wikipedia.org/wiki/Archimedes" target="_blank">Archimedes</a></label
    >
  </lion-checkbox>
  <lion-checkbox .choiceValue="${'Francis Bacon'}">
    <label slot="label"
      ><a href="https://wikipedia.org/wiki/Francis_Bacon" target="_blank">Francis Bacon</a></label
    >
  </lion-checkbox>
  <lion-checkbox .choiceValue="${'Marie Curie'}">
    <label slot="label"
      ><a href="https://wikipedia.org/wiki/Marie_Curie" target="_blank">Marie Curie</a></label
    >
  </lion-checkbox>
</lion-checkbox-group>

Help text

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

<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.

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.

<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.

<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.

<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>

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub!