Checkbox Group

Used for choosing multiple options from a group of related choices, such as filters.

Coming soon! This component will be available in SWAN v3.44.0. Stay tuned!

UsageGuidelines

Use Checkbox Group...

When multiple related options from a group can be selected.

Don't use Checkbox Group...

When the user must choose exactly one option from a group. Use Radio Group instead.
For selectable buttons, cards, tiles, or color swatches. Use Choice Group instead.
For a standalone option. Use Checkbox instead.

<CheckboxGroup aria-label="Filter by style">
  <Checkbox value="elegant">Elegant</Checkbox>
  <Checkbox value="modern">Modern</Checkbox>
  <Checkbox value="ugly">Ugly</Checkbox>
</CheckboxGroup>

<CheckboxGroup aria-label="Filter by style">
  <Checkbox value="elegant">Elegant</Checkbox>
  <Checkbox value="modern">Modern</Checkbox>
  <Checkbox value="ugly">Ugly</Checkbox>
</CheckboxGroup>

Disabled

Use disabled on any Checkboxes within Checkbox Group to prevent them from being selected or deselected.

To disable the entire group, use disabled on each item.

<CheckboxGroup aria-label="Disabled example">
  <Checkbox value="elegant" disabled>
    Elegant
  </Checkbox>
  <Checkbox value="modern" disabled>
    Modern
  </Checkbox>
  <Checkbox value="ugly" disabled>
    Ugly
  </Checkbox>
</CheckboxGroup>

<CheckboxGroup aria-label="Disabled example">
  <Checkbox value="elegant" disabled>
    Elegant
  </Checkbox>
  <Checkbox value="modern" disabled>
    Modern
  </Checkbox>
  <Checkbox value="ugly" disabled>
    Ugly
  </Checkbox>
</CheckboxGroup>

Required

Use required on a Checkbox to indicate that this specific option must be checked, such as an agreement the user must accept.

<CheckboxGroup aria-label="Filter by style">
  <Checkbox value="elegant" required>
    Elegant
  </Checkbox>
  <Checkbox value="modern">Modern</Checkbox>
  <Checkbox value="ugly">Ugly</Checkbox>
</CheckboxGroup>

<CheckboxGroup aria-label="Filter by style">
  <Checkbox value="elegant" required>
    Elegant
  </Checkbox>
  <Checkbox value="modern">Modern</Checkbox>
  <Checkbox value="ugly">Ugly</Checkbox>
</CheckboxGroup>

Unlike a Radio Group, a Checkbox Group has no built-in way to require selection. Refer to the Guidelines tab for an example of how you can use state to enforce minimum and maximum selections.

Labels, errors, and helper text

Use the FormField components to add a label, error message, or helper text to a Checkbox Group. They apply the necessary ARIA attributes for you, so you don't need to add them yourself.

Managing State

Controlled

Use selection and onSelectionChange on Checkbox Group to control the selected values. selection is an array of the values of the currently selected Checkbox components, or an empty array ([]) if nothing is selected. onSelectionChange receives the updated array and the native change event. Update your state in the handler so the group reflects the new selection.

() => {
  const [filters, setFilters] = React.useState(['elegant', 'modern'])

  return (
    <CheckboxGroup
      aria-label="Filter by style"
      selectedValues={filters}
      onSelectedValuesChange={setFilters}
    >
      <Checkbox value="elegant">Elegant</Checkbox>
      <Checkbox value="modern">Modern</Checkbox>
      <Checkbox value="ugly">Ugly</Checkbox>
    </CheckboxGroup>
  )
}

() => {
  const [filters, setFilters] = React.useState(['elegant', 'modern'])

  return (
    <CheckboxGroup
      aria-label="Filter by style"
      selectedValues={filters}
      onSelectedValuesChange={setFilters}
    >
      <Checkbox value="elegant">Elegant</Checkbox>
      <Checkbox value="modern">Modern</Checkbox>
      <Checkbox value="ugly">Ugly</Checkbox>
    </CheckboxGroup>
  )
}

Uncontrolled

Omit selectedValues to allow the browser to manage the state. Optionally, use defaultSelectedValues to set the initially selected values, and/or pass onSelectedValuesChange to react to changes (for example, to track the selection) without taking over the state.

<CheckboxGroup
  aria-label="Filter by style"
  defaultSelectedValues={['ugly']}
  onSelectedValuesChange={selection => trackSelection(selection)}
>
  <Checkbox value="elegant">Elegant</Checkbox>
  <Checkbox value="modern">Modern</Checkbox>
  <Checkbox value="ugly">Ugly</Checkbox>
</CheckboxGroup>

<CheckboxGroup
  aria-label="Filter by style"
  defaultSelectedValues={['ugly']}
  onSelectedValuesChange={selection => trackSelection(selection)}
>
  <Checkbox value="elegant">Elegant</Checkbox>
  <Checkbox value="modern">Modern</Checkbox>
  <Checkbox value="ugly">Ugly</Checkbox>
</CheckboxGroup>

Accessibility

Both Checkbox Group and Checkbox must have a localized accessible name.

Checkbox Group

Use a FormLabel to provide a visible and accessible name (recommended, see Labels, helpers, and error text). Alternatively, use custom ARIA labels (see Accessibility guidelines).

Checkbox

Refer to the Checkbox usage guidelines.

Select All

For a “select all” and/or “clear all” experience, use a standalone Checkbox alongside your Checkbox Group to toggle the selection.

() => {
  const allOccasions = ['Birthday', 'Baby', 'Business']

  const [selectedOccasions, setSelectedOccasions] = React.useState(allOccasions)
  const isAllSelected = selectedOccasions.length === allOccasions.length

  return (
    <FlexBox flexDirection="column" gap="between-controls">
      <Checkbox
        value="select-all"
        checked={isAllSelected}
        onChange={() => setSelectedOccasions(isAllSelected ? [] : allOccasions)}
      >
        All occasions
      </Checkbox>
      <CheckboxGroup
        aria-label="Filter by occasion"
        selectedValues={selectedOccasions}
        onSelectedValuesChange={setSelectedOccasions}
      >
        {allOccasions.map(v => (
          <Checkbox key={v} value={v}>
            {v}
          </Checkbox>
        ))}
      </CheckboxGroup>
    </FlexBox>
  )
}

() => {
  const allOccasions = ['Birthday', 'Baby', 'Business']

  const [selectedOccasions, setSelectedOccasions] = React.useState(allOccasions)
  const isAllSelected = selectedOccasions.length === allOccasions.length

  return (
    <FlexBox flexDirection="column" gap="between-controls">
      <Checkbox
        value="select-all"
        checked={isAllSelected}
        onChange={() => setSelectedOccasions(isAllSelected ? [] : allOccasions)}
      >
        All occasions
      </Checkbox>
      <CheckboxGroup
        aria-label="Filter by occasion"
        selectedValues={selectedOccasions}
        onSelectedValuesChange={setSelectedOccasions}
      >
        {allOccasions.map(v => (
          <Checkbox key={v} value={v}>
            {v}
          </Checkbox>
        ))}
      </CheckboxGroup>
    </FlexBox>
  )
}

Indeterminate

To communicate a “mixed selection state”, use indeterminate on the standalone Checkbox when only some are selected.

() => {
  const allOccasions = ['Birthday', 'Baby', 'Business']

  const [selectedOccasions, setSelectedOccasions] = React.useState(['Birthday'])
  const isAllSelected = selectedOccasions.length === allOccasions.length
  const isSomeSelected = selectedOccasions.length > 0 && !isAllSelected

  return (
    <FlexBox flexDirection="column" gap="between-controls">
      <Checkbox
        value="select-all"
        checked={isAllSelected}
        indeterminate={isSomeSelected}
        onChange={() => setSelectedOccasions(isAllSelected ? [] : allOccasions)}
      >
        All occasions
      </Checkbox>

      <CheckboxGroup
        aria-label="Filter by occasion"
        selectedValues={selectedOccasions}
        onSelectedValuesChange={setSelectedOccasions}
      >
        {allOccasions.map(v => (
          <Checkbox key={v} value={v}>
            {v}
          </Checkbox>
        ))}
      </CheckboxGroup>
    </FlexBox>
  )
}

() => {
  const allOccasions = ['Birthday', 'Baby', 'Business']

  const [selectedOccasions, setSelectedOccasions] = React.useState(['Birthday'])
  const isAllSelected = selectedOccasions.length === allOccasions.length
  const isSomeSelected = selectedOccasions.length > 0 && !isAllSelected

  return (
    <FlexBox flexDirection="column" gap="between-controls">
      <Checkbox
        value="select-all"
        checked={isAllSelected}
        indeterminate={isSomeSelected}
        onChange={() => setSelectedOccasions(isAllSelected ? [] : allOccasions)}
      >
        All occasions
      </Checkbox>

      <CheckboxGroup
        aria-label="Filter by occasion"
        selectedValues={selectedOccasions}
        onSelectedValuesChange={setSelectedOccasions}
      >
        {allOccasions.map(v => (
          <Checkbox key={v} value={v}>
            {v}
          </Checkbox>
        ))}
      </CheckboxGroup>
    </FlexBox>
  )
}

Min and Max

Unlike a Radio Group, a Checkbox Group has no built-in way to require how many options are selected.

To enforce a minimum number of selections, you can show a FormError when the number of selected values doesn’t meet the minimum.

() => {
  const [printLocations, setPrintLocations] = React.useState([])
  const [hasAttemptedSubmit, setHasAttemptedSubmit] = React.useState(true)

  const handleSubmit = event => {
    event.preventDefault()
    setHasAttemptedSubmit(true)

    // Minimum selection is 1.
    // Block adding to cart until at least one print location is selected.
    if (printLocations.length === 0) return

    // ...add the customized product to the cart
  }

  return (
    // Use noValidate to show our own FormError instead of the browser's popup
    <StandardForm onSubmit={handleSubmit} noValidate>
      <FormField>
        <FormLabel>Choose where your design will be printed</FormLabel>
        <FormInputGroup>
          <CheckboxGroup
            aria-label="Print locations"
            selectedValues={printLocations}
            onSelectedValuesChange={setPrintLocations}
          >
            <Checkbox value="front">Front</Checkbox>
            <Checkbox value="back">Back</Checkbox>
            <Checkbox value="left-sleeve">Left sleeve</Checkbox>
            <Checkbox value="right-sleeve">Right sleeve</Checkbox>
          </CheckboxGroup>
          {hasAttemptedSubmit && printLocations.length === 0 && (
            <FormError>Select at least one print location.</FormError>
          )}
        </FormInputGroup>
      </FormField>

      <Button type="submit">Add to cart</Button>
    </StandardForm>
  )
}

() => {
  const [printLocations, setPrintLocations] = React.useState([])
  const [hasAttemptedSubmit, setHasAttemptedSubmit] = React.useState(true)

  const handleSubmit = event => {
    event.preventDefault()
    setHasAttemptedSubmit(true)

    // Minimum selection is 1.
    // Block adding to cart until at least one print location is selected.
    if (printLocations.length === 0) return

    // ...add the customized product to the cart
  }

  return (
    // Use noValidate to show our own FormError instead of the browser's popup
    <StandardForm onSubmit={handleSubmit} noValidate>
      <FormField>
        <FormLabel>Choose where your design will be printed</FormLabel>
        <FormInputGroup>
          <CheckboxGroup
            aria-label="Print locations"
            selectedValues={printLocations}
            onSelectedValuesChange={setPrintLocations}
          >
            <Checkbox value="front">Front</Checkbox>
            <Checkbox value="back">Back</Checkbox>
            <Checkbox value="left-sleeve">Left sleeve</Checkbox>
            <Checkbox value="right-sleeve">Right sleeve</Checkbox>
          </CheckboxGroup>
          {hasAttemptedSubmit && printLocations.length === 0 && (
            <FormError>Select at least one print location.</FormError>
          )}
        </FormInputGroup>
      </FormField>

      <Button type="submit">Add to cart</Button>
    </StandardForm>
  )
}

To enforce a maximum number of selections, you can show a FormHelper once the number of selected values meets the maximum, and disable the remaining unselected options.

() => {
  const MAX_SELECTIONS = 3
  const finishes = [
    { value: 'matte', label: 'Matte' },
    { value: 'gloss', label: 'Gloss' },
    { value: 'foil', label: 'Foil' },
    { value: 'embossed', label: 'Embossed' },
  ]

  const [selectedFinishes, setSelectedFinishes] = React.useState([
    'matte',
    'gloss',
    'foil',
  ])
  const maxReached = selectedFinishes.length >= MAX_SELECTIONS

  return (
    <FormField>
      <FormLabel>Choose up to three finishes</FormLabel>
      <FormInputGroup>
        <CheckboxGroup
          selectionMode="multiple"
          selectedValues={selectedFinishes}
          onSelectedValuesChange={setSelectedFinishes}
        >
          {finishes.map(({ value, label }) => (
            <Checkbox
              key={value}
              value={value}
              // Only disable options that aren't already selected, so users
              // can always deselect one to make room for another
              disabled={maxReached && !selectedFinishes.includes(value)}
            >
              {label}
            </Checkbox>
          ))}
        </CheckboxGroup>

        {maxReached && (
          <FormHelper>
            You can choose up to {MAX_SELECTIONS} finishes. Deselect one to
            choose another.
          </FormHelper>
        )}
      </FormInputGroup>
    </FormField>
  )
}

() => {
  const MAX_SELECTIONS = 3
  const finishes = [
    { value: 'matte', label: 'Matte' },
    { value: 'gloss', label: 'Gloss' },
    { value: 'foil', label: 'Foil' },
    { value: 'embossed', label: 'Embossed' },
  ]

  const [selectedFinishes, setSelectedFinishes] = React.useState([
    'matte',
    'gloss',
    'foil',
  ])
  const maxReached = selectedFinishes.length >= MAX_SELECTIONS

  return (
    <FormField>
      <FormLabel>Choose up to three finishes</FormLabel>
      <FormInputGroup>
        <CheckboxGroup
          selectionMode="multiple"
          selectedValues={selectedFinishes}
          onSelectedValuesChange={setSelectedFinishes}
        >
          {finishes.map(({ value, label }) => (
            <Checkbox
              key={value}
              value={value}
              // Only disable options that aren't already selected, so users
              // can always deselect one to make room for another
              disabled={maxReached && !selectedFinishes.includes(value)}
            >
              {label}
            </Checkbox>
          ))}
        </CheckboxGroup>

        {maxReached && (
          <FormHelper>
            You can choose up to {MAX_SELECTIONS} finishes. Deselect one to
            choose another.
          </FormHelper>
        )}
      </FormInputGroup>
    </FormField>
  )
}

Checkbox Group

Use Checkbox Group...

Don't use Checkbox Group...

Disabled

Required

Labels, errors, and helper text

Managing State

Controlled

Uncontrolled

Accessibility

Checkbox Group

Checkbox

Select All

Indeterminate

Min and Max

Related