CheckboxGroup

Use a CheckboxGroup to control a group of checkboxes.

Figma LibraryView in StorybookView in PlayroomAPI Reference

Quick Start

Installation
npm install @adaptavant/eds-core
Import
import { CheckboxGroup } from '@adaptavant/eds-core';

Basic Usage​

A component to control a group of checkbox. Use legend prop to describe the purpose of the CheckboxGroup.

Animation Characters
const [selected, setSelected] = React.useState(['Daisy']);

return (
  <CheckboxGroup
    legend="Animation Characters"
    name="animation-characters"
    onChange={setSelected}
    value={selected}
  >
    <Checkbox label="Olaf" value="Olaf" />
    <Checkbox label="Minnie" value="Minnie" />
    <Checkbox label="Daisy" value="Daisy" />
  </CheckboxGroup>
);
View in Playroom

Description​

A description of the CheckboxGroup. Provides a hint such as specific requirements for what to choose.

Disney CharactersChoose one or more characters from the list below
const [selected, setSelected] = React.useState(['Woody']);

return (
  <CheckboxGroup
    description="Choose one or more characters from the list below"
    legend="Disney Characters"
    name="disney-characters"
    onChange={setSelected}
    value={selected}
  >
    <Checkbox label="Ariel" value="Ariel" />
    <Checkbox label="Woody" value="Woody" />
    <Checkbox label="Simba" value="Simba" />
  </CheckboxGroup>
);
View in Playroom

Managing state​

The CheckboxGroup component accepts a value and onChange prop, allowing you to control its state. value is an array of the currently selected values, and onChange receives the full new array whenever a checkbox is toggled.

Shrek CharactersChoose one or more characters from the list below
const [selected, setSelected] = React.useState(['Shrek']);

return (
  <CheckboxGroup
    description="Choose one or more characters from the list below"
    legend="Shrek Characters"
    name="shrek-characters"
    onChange={setSelected}
    value={selected}
  >
    <Checkbox label="Shrek" value="Shrek" />
    <Checkbox label="Fiona" value="Fiona" />
    <Checkbox label="Donkey" value="Donkey" />
  </CheckboxGroup>
);
View in Playroom

Name​

Use name prop to name the CheckboxGroup.

Fictional CharactersChoose one or more characters from the list below
const [selected, setSelected] = React.useState(['Pluto']);

return (
  <CheckboxGroup
    description="Choose one or more characters from the list below"
    legend="Fictional Characters"
    name="fictional-characters"
    onChange={setSelected}
    value={selected}
  >
    <Checkbox label="Pluto" value="Pluto" />
    <Checkbox label="Rex" value="Rex" />
    <Checkbox label="Rapunzel" value="Rapunzel" />
  </CheckboxGroup>
);
View in Playroom

Disabled​

Use the isDisabled prop to indicate that a CheckboxGroup or Checkbox is inactive or inaccessible.

Preferred contact methodsPlease check all that apply.
// disable the checkbox group
const [selected, setSelected] = React.useState(['Email']);

return (
  <CheckboxGroup
    description="Please check all that apply."
    isDisabled
    legend="Preferred contact methods"
    name="contact-methods"
    onChange={setSelected}
    value={selected}
  >
    <Checkbox label="Phone" value="Phone" />
    <Checkbox label="Email" value="Email" />
    <Checkbox label="SMS" value="Sms" />
  </CheckboxGroup>
);
View in Playroom

isDisabled prop accepts a boolean or a callback function.

Hogwarts HousesChoose one or more Houses from the list below
const [selected, setSelected] = React.useState(['Helga Hufflepuff']);
const isDisabled = (value) => value === 'Salazar Slytherin';

return (
  <CheckboxGroup
    description="Choose one or more Houses from the list below"
    legend="Hogwarts Houses"
    name="hogwarts-houses"
    onChange={setSelected}
    value={selected}
    isDisabled={isDisabled}
  >
    <Checkbox label="Godric Gryffindor" value="Godric Gryffindor" />
    <Checkbox label="Salazar Slytherin" value="Salazar Slytherin" />
    <Checkbox label="Helga Hufflepuff" value="Helga Hufflepuff" />
  </CheckboxGroup>
);
View in Playroom

Error​

Use the status and fieldMessage props to convey why the CheckboxGroup is in an error or warning state. The message is announced on focus for screen readers.

Preferred contact methodsPlease check all that apply.
const [selected, setSelected] = React.useState([]);

return (
  <CheckboxGroup
    description="Please check all that apply."
    status="error"
    fieldMessage="Please select at least one option."
    isRequired
    legend="Preferred contact methods"
    name="contact-methods-error"
    onChange={setSelected}
    value={selected}
  >
    <Checkbox label="Phone" value="Phone" />
    <Checkbox label="Email" value="Email" />
    <Checkbox label="SMS" value="Sms" />
  </CheckboxGroup>
);
View in Playroom

Without description​

The description prop is optional. You can omit it when the legend on its own makes the choice clear or there is no use case for it.

Select your preferred contact methods
const [selected, setSelected] = React.useState([]);

return (
  <CheckboxGroup
    legend="Select your preferred contact methods"
    name="prefer-contact-methods"
    onChange={setSelected}
    value={selected}
  >
    <Checkbox label="Phone" value="Phone" />
    <Checkbox label="Email" value="Email" />
    <Checkbox label="SMS" value="Sms" />
  </CheckboxGroup>
);
View in Playroom

Orientation​

The orientation prop allows you to control the layout direction of the CheckboxGroup. Set orientation="horizontal" to display options side by side, or orientation="vertical" to stack them. The default is vertical.

Hogwarts HousesChoose one or more Houses from the list below
CharactersChoose one or more characters from the list below
const [selectedHouses, setSelectedHouses] = React.useState(['Helga Hufflepuff']);
const [selectedCharacters, setSelectedCharacters] = React.useState(['Luna Lovegood']);

return (
  <>
    <CheckboxGroup
      description="Choose one or more Houses from the list below"
      legend="Hogwarts Houses"
      name="hp-houses"
      onChange={setSelectedHouses}
      value={selectedHouses}
      orientation="horizontal"
    >
      <Checkbox label="Godric Gryffindor" value="Godric Gryffindor" />
      <Checkbox label="Salazar Slytherin" value="Salazar Slytherin" />
      <Checkbox label="Helga Hufflepuff" value="Helga Hufflepuff" />
    </CheckboxGroup>

    <CheckboxGroup
      description="Choose one or more characters from the list below"
      legend="Characters"
      name="characters"
      onChange={setSelectedCharacters}
      value={selectedCharacters}
      orientation="vertical"
    >
      <Checkbox label="Luna Lovegood" value="Luna Lovegood" />
      <Checkbox label="Neville Longbottom" value="Neville Longbottom" />
      <Checkbox label="Ginny Weasley" value="Ginny Weasley" />
    </CheckboxGroup>
  </>
);
View in Playroom

API Reference​

CheckboxGroup

PropDefaultDescription
children_ReactNode
The Checkbox components to be included in the group.
description?_ReactNode
Helpful text that appears below the legend to provide additional information or instructions about the checkbox options.
fieldMessage?_ReactNode
Text that appears below the checkbox options to explain the validation state, such as when a required selection hasn't been made. Use with the status prop.
id?_string
A unique identifier for the checkbox group, useful for accessibility and form handling.
isRequired?falseboolean
When true, indicates that the user must select at least one of the checkbox options before submitting the form.
legend_ReactNode
The title or heading for the checkbox group that explains what the options are for.
orientation?'vertical''horizontal' | 'vertical'
Controls how the checkboxes are arranged - either side-by-side (horizontal) or stacked (vertical).
isDisabled?falseboolean
Makes all checkboxes non-clickable when set to true. Can also be a function that decides which options should be disabled based on their value.
name_string
A required field that groups the checkboxes together. Important for form submission.
onBlur?_(selectedValues: string[]) => void
A function that runs when the user clicks or tabs away from a checkbox, receiving the currently selected values.
onChange_(selectedValues: string[]) => void
A required function that runs whenever the user toggles a checkbox, receiving the full array of selected values.
size?'standard''standard' | 'large'
Controls the size of all checkboxes in the group - either normal sized or larger for better visibility.
status?_'error' | 'warning'
The validation state of the checkbox group. Styles the group and the fieldMessage to signify the state, and announces the group as invalid to screen-readers when set to error.
value_string[]
The array of currently selected checkbox values. Required to make this a controlled component.

Note: The CheckboxGroup component inherits several props from the Fieldset component and combines them with checkbox-specific functionality to create accessible form controls.

Style API​

Our design system components include style props that allow you to easily customize different parts of each component to match your design needs.

Please refer to the Style API documentation for more insights.

CheckboxGroup parts​

Payment MethodsSelect your preferred payment methods
const [selected, setSelected] = React.useState([]);
const error = selected.length === 0 ? 'Please select atleast one payment method' : '';

return (
  <CheckboxGroup
    legend="Payment Methods"
    name="payment"
    onChange={setSelected}
    value={selected}
    description="Select your preferred payment methods"
    className="border border-input rounded-8px w-full p-4"
    fieldMessage={error}
    status="error"
    classNames={{
      legend: "text-positive underline",
      description: "text-link italic",
      errorMessage: "text-caution",
      errorTrack: "bg-neutral-secondary px-2 py-1",
      errorIcon: "fill-critical",
      wrapper: "bg-neutral-secondary p-4 rounded-8px",
    }}
  >
    <Checkbox label="Cash" value="cash" />
    <Checkbox label="Credit Card" value="card" />
    <Checkbox label="Bank Transfer" value="transfer" />
  </CheckboxGroup>
);
View in Playroom
Stylable PartsDescription
rootThe root container of the checkbox group component, wrapping all inner elements.
legendThe legend text that serves as the heading for the checkbox group.
descriptionDescription text providing additional information about the checkbox group.
errorMessageThe error message text displayed when validation fails.
errorTrackContainer that wraps the error icon and error message.
errorIconThe icon displayed alongside the error message.
wrapperContainer that wraps the checkbox options within the group.

Usage guidelines​

Do

  1. Multiple selection in lists, forms, or tables: Implement CheckboxGroup in lists, forms, or tables when users need to choose one or more options from multiple related choices.
  2. Non-immediate selections: Use CheckboxGroup when the selection doesn't take immediate effect and requires form submission.

Don’t

  1. Single selection only: Avoid using CheckboxGroup when users may select only one option from the set; use RadioGroup instead.
  2. Immediate selections, especially on mobile: For selections that take immediate effect, particularly on mobile devices, use Toggle instead of CheckboxGroup.
  3. Visual clarity issues: If it's visually challenging to discern whether a selection turns something on or off, prefer using Toggle for clearer visual feedback.