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's inside this element.

Live Demo/Documentation

See our storybook for a live demo and API documentation

How to use

Installation

npm i --save @lion/checkbox @lion/checkbox-group

import '@lion/checkbox/lion-checkbox.js';
import '@lion/checkbox-group/lion-checkbox-group.js';

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>

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.