Skip to main content
Components

Checkboxes

Let users select one or more options by using the checkboxes component.

Children are Items, each with an Input, followed by a Conditional where it reveals one.

Read the Design System guidance for checkboxes

Import

import * as Checkboxes from 'govuk-react/checkboxes';

Examples

Default

Code
<Checkboxes.Field
  idPrefix="nationality"
  legend="What is your nationality?"
  hint="Select all that apply"
>
  {items}
</Checkboxes.Field>

Checkbox small

Code
<Checkboxes.Field
  idPrefix="nationality"
  legend="What is your nationality?"
  hint="Select all that apply"
  small
>
  {items}
</Checkboxes.Field>

Checkbox preselected

Code
<Checkboxes.Field
  idPrefix="nationality"
  legend="What is your nationality?"
  hint="Select all that apply"
>
  {(
    <>
      <Checkboxes.ItemComposite
        id="waste"
        name="waste"
        value="carcasses"
        label="Waste from animal carcasses"
        defaultChecked
      />
      <Checkboxes.ItemComposite id="waste-2" name="waste" value="mines" label="Waste from mines or quarries" />
      <Checkboxes.ItemComposite id="waste-3" name="waste" value="farm" label="Farm or agricultural waste" disabled />
    </>
  )}
</Checkboxes.Field>

With error

Code
<Checkboxes.Field
  idPrefix="nationality"
  legend="What is your nationality?"
  hint="Select all that apply"
  errorMessage="Select if you are British, Irish or a citizen of a different country"
>
  {items}
</Checkboxes.Field>

With none option

As in the Design System's example, checking "No" unchecks the countries, and checking a country unchecks "No".

Code
<Checkboxes.Field
  idPrefix="countries"
  legend="Will you be travelling to any of these countries?"
  hint="Select all countries that apply"
  items={[
    { id: 'countries', name: 'countries', value: 'france', label: 'France' },
    { id: 'countries-2', name: 'countries', value: 'portugal', label: 'Portugal' },
    { id: 'countries-3', name: 'countries', value: 'spain', label: 'Spain' },
    { divider: 'or' },
    {
      id: 'countries-4',
      name: 'countries',
      value: 'none',
      label: 'No, I will not be travelling to any of these countries',
      exclusive: true,
    },
  ]}
/>

With conditional

Code
<Checkboxes.Field
  idPrefix="contact"
  legend="How would you like to be contacted?"
  hint="Select all options that are relevant to you"
>
  {(
    <>
      <Checkboxes.ItemComposite
        id="contact"
        name="contact"
        value="email"
        label="Email"
        defaultChecked
        conditional={<InputField id="contact-by-email" name="contactByEmail" type="email" label="Email address" />}
      />
      <Checkboxes.ItemComposite
        id="contact-2"
        name="contact"
        value="phone"
        label="Phone"
        conditional={<InputField id="contact-by-phone" name="contactByPhone" type="tel" label="Phone number" />}
      />
      <Checkboxes.ItemComposite id="contact-3" name="contact" value="text" label="Text message" />
    </>
  )}
</Checkboxes.Field>

API reference

Checkboxes.Root

Let users select one or more options by using the checkboxes component.

Children are Items, each with an Input, followed by a Conditional where it reveals one.

PropType
smallboolean

Checkboxes.Conditional

Content revealed while its checkbox is checked, straight after its Item. Pass the checkbox's checked or defaultChecked as checked.

PropType
checkedboolean

Checkboxes.Divider

No props of its own. Other props are passed to the element it renders.

Checkboxes.Field

Let users select one or more options by using the checkboxes component.

Children are ItemComposites and Dividers.

PropType
legendRequired

The legend for the fieldset used by the checkboxes component.

ReactNode
smallboolean
hint

Can be used to add a hint to the checkboxes component.

ReactNode
legendSize"s" | "m" | "l" | "xl"
legendIsPageHeadingboolean
idPrefixRequired

This is used to prefix the id attribute for each checkbox item input, hint and error message, separated by -.

string
errorMessage

Can be used to add an error message to the checkboxes component. The error message component will not display if you use a falsy value for errorMessage, for example false or null.

ReactNode
items

Prefer children, which memoise and re-render better.

(ItemCompositeProps | { divider: any; })[]

Checkboxes.Hint

No props of its own. Other props are passed to the element it renders.

Checkboxes.Input

PropType
controls

The id of the Conditional this checkbox reveals.

string
exclusive

For an option such as "None of these": once JavaScript runs, checking it unchecks the other checkboxes with its name, and checking one of them unchecks it.

boolean
data-behaviour

govuk-frontend's way to make it exclusive: "exclusive".

string

Checkboxes.Item

No props of its own. Other props are passed to the element it renders.

Checkboxes.ItemComposite

PropType
labelRequired

The label used by each checkbox item within the checkboxes component.

ReactNode
hint

Can be used to add a hint to each checkbox item within the checkboxes component.

ReactNode
conditional

Provide additional content to reveal when the checkbox is checked.

ReactNode
exclusive

For an option such as "None of these": once JavaScript runs, checking it unchecks the other checkboxes with its name, and checking one of them unchecks it.

boolean

Checkboxes.Label

PropType
size"s" | "m" | "l" | "xl"
isPageHeading

Whether the label also acts as the heading for the page.

boolean