lion/packages/checkbox-group

Checkbox Group

lion-checkbox-group component enhances the functionality of the native <input type="checkbox"> element. Its purpose is to provide a way for users to check multiple options amongst a set of choices, or to function as a single toggle.

You should use <lion-checkbox> elements as the children of the <lion-checkbox-group>.

import { html } from '@lion/core';
import { Required, Validator } from '@lion/form-core';
import './lion-checkbox-group.js';
import './lion-checkbox-indeterminate.js';
import './lion-checkbox.js';

export default {
  title: 'Forms/Checkbox Group',
};

export const main = () => 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>
`;

Make sure that the checkbox-group also has a name attribute, this is necessary for the lion-form's serialization result.

Features

Since it extends from lion-fieldset, it has all the features a fieldset has.

How to use

Installation

npm i --save @lion/checkbox-group

import '@lion/checkbox-group/lion-checkbox-group.js';
import '@lion/checkbox-group/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:

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=${{ value: 'Marie Curie', checked: true }}
    ></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=${{ value: 'Marie Curie', checked: true }}
    ></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 = () => html`
  <lion-checkbox-group
    name="scientists[]"
    label="Favorite scientists"
    @model-value-changed=${e =>
      (document.getElementById('selectedDinosaur').innerText = JSON.stringify(
        e.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

export const indeterminate = () => html`
  <lion-checkbox-group name="scientists[]">
    <lion-checkbox-indeterminate label="Favorite scientists">
      <lion-checkbox slot="checkbox" label="Archimedes"></lion-checkbox>
      <lion-checkbox slot="checkbox" label="Francis Bacon"></lion-checkbox>
      <lion-checkbox slot="checkbox" label="Marie Curie"></lion-checkbox>
    </lion-checkbox-indeterminate>
  </lion-checkbox-group>
`;

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

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