Lion Logo Lion Guides Components Docs Blog Toggle darkmode

Checkbox Group: Features

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.

export const preselect = () => 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'} checked></lion-checkbox>
    <lion-checkbox
      label="Marie Curie"
      .modelValue=$
    ></lion-checkbox>
  </lion-checkbox-group>
`;

Disabled

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

export const disabled = () => html`
  <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"
      .modelValue=$
    ></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.

export const label = () => html`
  <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>.

export const helpText = () => html`
  <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.

export const indeterminateSiblings = () => html`
  <lion-checkbox-group name="scientists[]" label="Favorite scientists">
    <lion-checkbox-indeterminate label="Old Greek scientists">
      <lion-checkbox
        slot="checkbox"
        label="Archimedes"
        .choiceValue=${'Archimedes'}
      ></lion-checkbox>
      <lion-checkbox slot="checkbox" label="Plato" .choiceValue=${'Plato'}></lion-checkbox>
      <lion-checkbox
        slot="checkbox"
        label="Pythagoras"
        .choiceValue=${'Pythagoras'}
      ></lion-checkbox>
    </lion-checkbox-indeterminate>
    <lion-checkbox-indeterminate label="17th Century scientists">
      <lion-checkbox
        slot="checkbox"
        label="Isaac Newton"
        .choiceValue=${'Isaac Newton'}
      ></lion-checkbox>
      <lion-checkbox
        slot="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.

export const indeterminateChildren = () => html`
  <lion-checkbox-group name="scientists[]" label="Favorite scientists">
    <lion-checkbox-indeterminate label="Scientists">
      <lion-checkbox
        slot="checkbox"
        label="Isaac Newton"
        .choiceValue=${'Isaac Newton'}
      ></lion-checkbox>
      <lion-checkbox
        slot="checkbox"
        label="Galileo Galilei"
        .choiceValue=${'Galileo Galilei'}
      ></lion-checkbox>
      <lion-checkbox-indeterminate slot="checkbox" label="Old Greek scientists">
        <lion-checkbox
          slot="checkbox"
          label="Archimedes"
          .choiceValue=${'Archimedes'}
        ></lion-checkbox>
        <lion-checkbox slot="checkbox" label="Plato" .choiceValue=${'Plato'}></lion-checkbox>
        <lion-checkbox
          slot="checkbox"
          label="Pythagoras"
          .choiceValue=${'Pythagoras'}
        ></lion-checkbox>
      </lion-checkbox-indeterminate>
    </lion-checkbox-indeterminate>
  </lion-checkbox-group>
`;