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.

GitHub·Storybook·Playroom·Figma

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

<FormControl label="Extras" id="extras" name="extras" valid={false} validated={false} error="Please select which extras you need.">
  <CheckboxGroup
    options={{
      chiro: 'Chiro',
      dietaryAdvice: 'Dietary Advice',
      generalDental: 'General Dental',
      majorDental: 'Major Dental',
      occupationalTherapy: 'Occupational Therapy',
      optical: 'Optical'
    }}
    value={['optical', 'optical']}
  />
</FormControl>

<FormControl label="Extras" id="extras" name="extras" valid={false} validated={false} error="Please select which extras you need.">
  <CheckboxGroup
    options={{
      chiro: 'Chiro',
      dietaryAdvice: 'Dietary Advice',
      generalDental: 'General Dental',
      majorDental: 'Major Dental',
      occupationalTherapy: 'Occupational Therapy',
      optical: 'Optical'
    }}
    value={['optical', 'optical']}
  />
</FormControl>

With subtitles

<FormControl label="Extras" id="extras2" name="extras2" valid={false} validated={false} error="Please select which extras you need.">
  <CheckboxGroup
    options={{
      dental: {
        label: 'Dental',
        subtitle: 'Major and general'
      },
      physio: {
        label: 'Physio',
        subtitle: 'Physical therapy'
      },
      optical: {
        label: 'Optical',
        subtitle: 'Glasses and lenses'
      },
      chiro: {
        label: 'Chiro',
        subtitle: 'Spine and musculoskeletal therapy'
      },
      massage: {
        label: 'Massage',
        subtitle: 'Deep tissue pain relief'
      }
    }}
    value={['dental', 'optical']}
  />
</FormControl>

<FormControl label="Extras" id="extras2" name="extras2" valid={false} validated={false} error="Please select which extras you need.">
  <CheckboxGroup
    options={{
      dental: {
        label: 'Dental',
        subtitle: 'Major and general'
      },
      physio: {
        label: 'Physio',
        subtitle: 'Physical therapy'
      },
      optical: {
        label: 'Optical',
        subtitle: 'Glasses and lenses'
      },
      chiro: {
        label: 'Chiro',
        subtitle: 'Spine and musculoskeletal therapy'
      },
      massage: {
        label: 'Massage',
        subtitle: 'Deep tissue pain relief'
      }
    }}
    value={['dental', 'optical']}
  />
</FormControl>

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.

Prop	Type	Default	Description
`options` (required)	object		Two structures are supported. Both are an object, with keys mapping to the option value. The property value maps to either the checkbox label as string, or an object with `label` and `subtitle` keys.
`boldLabel`	boolean	`false`	Whether the labels are bold. If a subtitle is provided for an option, the default value changes to `true` for that option.
`value`	array	`[]`	An array of selected values.
`component`	string or React component	`Checkbox`	The component used to render a checkbox.

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.

Edit this page