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.
| Prop | Type |
|---|---|
small | boolean |
Checkboxes.Conditional
Content revealed while its checkbox is checked, straight after its Item. Pass the checkbox's checked or defaultChecked as checked.
| Prop | Type |
|---|---|
checked | boolean |
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.
| Prop | Type |
|---|---|
legendRequiredThe legend for the fieldset used by the checkboxes component. | ReactNode |
small | boolean |
hintCan be used to add a hint to the checkboxes component. | ReactNode |
legendSize | "s" | "m" | "l" | "xl" |
legendIsPageHeading | boolean |
idPrefixRequiredThis is used to prefix the | string |
errorMessageCan 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 | ReactNode |
itemsPrefer 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
| Prop | Type |
|---|---|
controlsThe id of the | string |
exclusiveFor 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-behaviourgovuk-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
| Prop | Type |
|---|---|
labelRequiredThe label used by each checkbox item within the checkboxes component. | ReactNode |
hintCan be used to add a hint to each checkbox item within the checkboxes component. | ReactNode |
conditionalProvide additional content to reveal when the checkbox is checked. | ReactNode |
exclusiveFor 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
| Prop | Type |
|---|---|
size | "s" | "m" | "l" | "xl" |
isPageHeadingWhether the label also acts as the heading for the page. | boolean |