Design Tokens for Mesh have just been released!
Skip to content

Checkbox Group

A checkbox group can be used when there are multiple checkbox options available. If a single option is needed, consider a checkbox. When a user is restricted to choosing one option from many options available, consider using a radio group.

Installation

bash
npm install @nib-components/checkbox-group

As a form input, @nib-components/form-control must wrap this component to provide an accessible label, help text, and validation styling. Note: You will also need to install the peerDependencies @nib/icons and @nib-components/theme.

Usage

jsx
import CheckboxGroup from '@nib-components/checkbox-group';

Interactive demo

js

With subtitles

js

Props

As the <CheckboxGroup/> is wrapped in a <FormControl/>, all FormControl props such as valid, validated, and disabled will be passed down to this component. This includes the id, name and label which will align with the for attribute on the <label>.

All props passed directly to <CheckboxGroup/> will be applied to the underlying <input> as attributes.

PropTypeDefaultDescription
options (required)object or arrayCan be an object or an array. See below for more detail.
boldLabelbooleanfalseWhether the labels are bold. If a subtitle is provided for an option, the default value changes to true for that option.
valuearray[]An array of selected values.
componentstring or React componentCheckboxThe component used to render a checkbox.

Options

The options prop accepts both an array and dictionary of items, and within each there are further configuration options.

Object

Simple key:value pairs where key is equal to the option value, and the value of the property is the label:

javascript
const options = {
small: 'Small',
medium: 'Medium',
large: 'Large'
};

Or a nested object when supporting subtitles or disabling individual options:

javascript
const options = {
small: {
label: 'Small',
subtitle: 'Lorem ipsum'
},
medium: {
label: 'Medium',
subtitle: 'Dolor sit amet'
},
large: {
label: 'Large',
subtitle: 'Consectetuer elit'
}
};

In certain situations you may find the need to pass a ReactNode as the label:

javascript
const options = {
one: (
<Columns space={3} verticalAlign="center">
<Column width="content">
<SupportSystemIcon />
</Column>
<Column>
<Copy>Lorem ipsum</Copy>
</Column>
</Columns>
),
two: (
<Columns space={3} verticalAlign="center">
<Column width="content">
<ShoppingCartSystemIcon />
</Column>
<Column>
<Copy>Dolor sit amet</Copy>
</Column>
</Columns>
)
};

Array

Using an array guarantees order.

When using an array each item must be an object with a value and label property, and can have a optional subtitle property and an optional disabled property:

javascript
const options = [
{value: 'small', label: 'Small'},
{value: 'medium', label: 'Medium'},
{value: 'large', label: 'Large'}
];

Similarly, when using an array options can have subtitles, be individually disabled and can use a ReactNode for the label:

javascript
const optionsWithSubtitles = [
{value: 'small', label: 'Small', subtitle: 'Lorem ipsum'},
{value: 'medium', label: 'Medium', subtitle: 'Dolor sit amet'},
{value: 'large', label: 'Large', subtitle: 'Consectetuer elit'}
];
const const optionsWithReactNodes = [
{
value: 'one',
label: (
<Columns space={3} verticalAlign="center">
<Column width="content">
<SupportSystemIcon />
</Column>
<Column>
<Copy>Lorem ipsum</Copy>
</Column>
</Columns>
)
},
{
value: 'two',
label: (
<Columns space={3} verticalAlign="center">
<Column width="content">
<ShoppingCartSystemIcon />
</Column>
<Column>
<Copy>Dolor sit amet</Copy>
</Column>
</Columns>
)
}
];

Considerations

When only one selection is required, consider using the Radio Group component.

Usability

Checkboxes are used when there are lists of options and the user may select any number of choices, including zero, one, or several. In other words, each checkbox is independent of all other checkboxes in the list, so checking one box doesn’t uncheck the others. If a user must select exactly one choice, consider Radio Group.

Accessibility

All input fields need to have a label and the label is linked to the form field using the id attribute. Note that the name attribute is also important for radio buttons and checkboxes to maintain the groupings. The inputs should have tab indexing in sequential order.

Subtitles

Subtitles are optional and should be used to provide more context to the option. Subtitles should be added to all options in the group, or none. Otherwise, alignment will suffer, especially if rendering the options inline.