Checkbox
Checkboxes let users select any number of options from a list, including none.
On this page
Preview
import { Checkbox, Fieldset, Hint } from '@govtech-bb/react';
<Fieldset
legend="How would you like to be contacted?"
aria-describedby="contact-description"
>
<Hint id="contact-description">Select all that apply</Hint>
<Checkbox name="contact" value="email" label="Email" />
<Checkbox name="contact" value="phone" label="Phone" />
<Checkbox name="contact" value="post" label="Post" />
</Fieldset>;<div class="govbb-form-group">
<fieldset class="govbb-fieldset" aria-describedby="contact-description">
<legend class="govbb-fieldset__legend">
How would you like to be contacted?
</legend>
<span class="govbb-hint" id="contact-description"
>Select all that apply</span
>
<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="contact-email"
type="checkbox"
name="contact"
value="email"
/>
<label class="govbb-checkbox-item__label" for="contact-email"
>Email</label
>
</div>
<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="contact-phone"
type="checkbox"
name="contact"
value="phone"
/>
<label class="govbb-checkbox-item__label" for="contact-phone"
>Phone</label
>
</div>
<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="contact-post"
type="checkbox"
name="contact"
value="post"
/>
<label class="govbb-checkbox-item__label" for="contact-post">Post</label>
</div>
</fieldset>
</div>The Checkbox component lets users select any number of options from a list, including none, or toggle a single option on or off. Each checkbox operates independently, so selecting one does not affect the others.
Usage
When to use
- Use checkboxes when users can select any number of options from a list.
- Use one checkbox for a single optional choice, such as receiving updates.
When not to use
- Do not use checkboxes when users must choose exactly one option; use radio buttons.
- Do not use separate “Yes” and “No” checkboxes because both can be selected.
Best practices
Explain how many options users can choose
Add a hint such as “Select all that apply” when more than one selection is
allowed. Group related choices in a fieldset with a clear legend.
Make every option easy to select
Place the checkbox before its label and connect them with matching id and
for values so the whole label activates the control. Avoid long, overloaded
groups; simplify or split the question when scanning becomes difficult.
Guidance
Group related checkboxes in a <fieldset> with a <legend> that frames the
question, for example “How would you like to be contacted?”. This associates
the options with their question for assistive technology.
Do not pre-select options. Pre-selected checkboxes make it more likely that users will not notice they have skipped a question, or will submit an answer they did not intend. Let users make an active choice.
Order options by relevance, listing the most common or recommended choices first. Fall back to alphabetical order only when no meaningful priority exists.
Make the number of selectable options clear. Do not assume users will infer from the visual difference between checkboxes and radio buttons that they can select more than one. Add a hint such as “Select all that apply” where it helps.
Per-option hints
Add a hint to an individual option when its label needs clarification. Link the
hint to the checkbox with aria-describedby.
import { Checkbox } from '@govtech-bb/react';
<Checkbox
name="nationality"
value="british"
label="British"
description="Including English, Scottish, Welsh and Northern Irish"
/>;<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="nationality-british"
type="checkbox"
name="nationality"
value="british"
aria-describedby="nationality-british-description"
/>
<label class="govbb-checkbox-item__label" for="nationality-british">
British
</label>
<span class="govbb-hint" id="nationality-british-description">
Including English, Scottish, Welsh and Northern Irish
</span>
</div>Single checkbox
Use a standalone checkbox, without a fieldset, for a single opt-in, such as accepting terms and conditions.
import { Checkbox } from '@govtech-bb/react';
<Checkbox name="terms" value="yes" label="I agree to the terms of service" />;<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="terms"
type="checkbox"
name="terms"
value="yes"
/>
<label class="govbb-checkbox-item__label" for="terms"
>I agree to the terms of service</label
>
</div>Conditional reveal
Show follow-up content when an option is ticked. The conditional block sits as a sibling of its checkbox item and appears only while that checkbox is checked.
import { Checkbox, Fieldset, FormGroup, Input, Label } from '@govtech-bb/react';
<Fieldset legend="How would you like to be contacted?">
<Checkbox
name="contact"
value="email"
label="Email"
conditional={
<FormGroup>
<Label htmlFor="c-email-addr">Email address</Label>
<Input id="c-email-addr" type="email" />
</FormGroup>
}
/>
<Checkbox
name="contact"
value="phone"
label="Phone"
conditional={
<FormGroup>
<Label htmlFor="c-phone-num">Phone number</Label>
<Input id="c-phone-num" type="tel" />
</FormGroup>
}
/>
</Fieldset>;<div class="govbb-form-group">
<fieldset class="govbb-fieldset">
<legend class="govbb-fieldset__legend">
How would you like to be contacted?
</legend>
<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="c-email"
type="checkbox"
name="contact"
value="email"
/>
<label class="govbb-checkbox-item__label" for="c-email">Email</label>
</div>
<div class="govbb-checkbox-item__conditional">
<div class="govbb-form-group">
<label class="govbb-label" for="c-email-addr">Email address</label>
<input class="govbb-input" id="c-email-addr" type="email" />
</div>
</div>
<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="c-phone"
type="checkbox"
name="contact"
value="phone"
/>
<label class="govbb-checkbox-item__label" for="c-phone">Phone</label>
</div>
<div class="govbb-checkbox-item__conditional">
<div class="govbb-form-group">
<label class="govbb-label" for="c-phone-num">Phone number</label>
<input class="govbb-input" id="c-phone-num" type="tel" />
</div>
</div>
</fieldset>
</div>Disabled checkboxes
Disable a checkbox only when an option is genuinely unavailable to the user, and say why in the label, for example “(unavailable)”. As with buttons, avoid disabling wherever possible: a disabled checkbox gives the user no information about what they need to do to enable it.
import { Checkbox } from '@govtech-bb/react';
<Checkbox name="contact" value="sms" label="SMS (unavailable)" disabled />;<div class="govbb-checkbox-item">
<input
class="govbb-checkbox"
id="sms"
type="checkbox"
name="contact"
value="sms"
disabled
/>
<label class="govbb-checkbox-item__label" for="sms">SMS (unavailable)</label>
</div>