Skip to contentSkip to navigationSkip to topbar
Figma
Star

Checkbox

A Checkbox is a form element that enables a binary choice and a Checkbox Group is a collection of Checkboxes.

Version 13.1.1
Github
Component preview theme
const CheckboxChecked = () => {
const [checked, setChecked] = React.useState(true);
return (
<Checkbox
checked={checked}
id="blm"
value="blm"
name="blm"
onChange={(event) => {
setChecked(event.target.checked);
}}
>
Enable SSL certificate validation
</Checkbox>
);
};
render(
<CheckboxChecked />
)

Guidelines

Guidelines page anchor

Checkbox Group

Checkbox Group page anchor

The Checkbox and Checkbox Group are used to enable binary choices. These can either be used for an individual choice or to form a collection of choices.

Checkbox groups are used when you have multiple binary choices to make but all choices belong to a single group or field. For example, choosing capabilities when searching for a Phone Number to provision from Twilio. By placing them in a group, users should be able to clearly understand which options make up the collection and also how those options are related to each other.

Accessibility

Accessibility page anchor
  • Checkbox groups must have a group legend that describes the collection.
    • The label should be visible.
    • The label may be visually hidden or provided via aria-label on the group component if the entire form is just a single checkbox group with no other form elements. The grouping should be visually implicit, but a description still needs to be provided for assistive technology.

Use a checkbox to present a user with a binary (e.g. on/off) choice that is part of a form. A checkbox should not be used to apply a user's choice instantly. In that case, such as enabling a system feature, you should consider using the Switch component.

  • A checkbox must have a visible label that is in close proximity to the control
  • HTML checkboxes don't natively support the required attribute. In cases where a checkbox is required to be checked:
    • Display a required indicator
    • Ensure the label text includes wording that successfully describes the requirement to the user that they should check the box
  • When in an error state, display an inline error message below the checkbox or checkbox group that clearly describes the error along with an icon that depicts the severity.
  • When displaying additional content based on checking a checkbox, be sure that the new content appears after the checkbox so that it is naturally discoverable by assistive technology users.

Controlled vs. uncontrolled checkboxes

Controlled vs. uncontrolled checkboxes page anchor

The checkbox can either be controlled, meaning there is an external state that determines if the checkbox is checked or not, or uncontrolled, meaning the checkbox manages its own state.

To make an uncontrolled checkbox, you do not pass the checked or onChange props. If you need the checkbox to be checked by default, use the defaultChecked prop.

Component preview theme
const UncontrolledCheckbox = () => {
return (
<Checkbox
id="uncontrolled"
value="uncontrolled"
name="uncontrolled"
defaultChecked
>
I am an uncontrolled checkbox
</Checkbox>
);
};
render(
<UncontrolledCheckbox />
)

To make a controlled checkbox, you must pass the checked and onChange props. You cannot use the defaultChecked prop in a controlled checkbox.

Component preview theme
const ControlledCheckbox = () => {
const [checked, setChecked] = React.useState(true);
return (
<Checkbox
id="controlled"
value="controlled"
name="controlled"
checked={checked}
onChange={(event) => {
setChecked(event.target.checked);
}}
>
I am a controlled checkbox
</Checkbox>
);
};
render(
<ControlledCheckbox />
)

Basic checkbox with label

Basic checkbox with label page anchor

A checkbox is always displayed next to a visible label.

Component preview theme
const CheckboxChecked = () => {
const [checked, setChecked] = React.useState(true);
return (
<Checkbox
checked={checked}
id="blm"
value="blm"
name="blm"
onChange={(event) => {
setChecked(event.target.checked);
}}
>
Enable SSL certificate validation
</Checkbox>
);
};
render(
<CheckboxChecked />
)

In cases where the checkbox requires additional context, you can display this information as help text below the checkbox control and label. This can help keep checkbox labels concise. In order to maintain styling consistency, be sure to use the helpText prop here instead of using the Help Text component.

Component preview theme
<Checkbox id="enabled" value="enabled" name="enabled" helpText="Determines if certificate validation is performed on all Twilio originated requests">
Enable SSL certificate validation
</Checkbox>

When a checkbox is required to be checked, a required indicator should be displayed alongside the label. The label text should also be written in such a way that this requirement is clear to the user.

Component preview theme
<Checkbox id="delete" value="delete" name="delete" required>
Confirm this message should be deleted
</Checkbox>

Multiple checkboxes and their labels are grouped together with a common group component. The group legend must be the first element inside the group. It must appear before any checkboxes or other content.

Component preview theme
<CheckboxGroup
name="desktop"
legend="Select the clients you would like to test."
>
<Checkbox id="apple_mail" value="apple_mail">
Apple Mail
</Checkbox>
<Checkbox id="outlook" value="outlook">
Outlook
</Checkbox>
</CheckboxGroup>

Checkbox group with help text

Checkbox group with help text page anchor

You can provide additional information about the group with the use of help text. Help text can appear after the group label but before the first group member. Each item in the group may also provide their own, individual help text.

Component preview theme
<CheckboxGroup
name="ad_partners"
legend="Which ad partnes would you like to advertise on?"
helpText="Select at least 1 ad partner to create a campaign."
>
<Checkbox
id="facebook"
value="facebook"
helpText={
<Text as="span" color="currentColor">
Questions? <Anchor href="http://paste.twilio.com">Click here to learn more</Anchor>.
</Text>
}
>
Facebook
</Checkbox>
<Checkbox
id="instagram"
value="instagram"
helpText={
<Text as="span" color="currentColor">
Questions? <Anchor href="http://paste.twilio.com">Click here to learn more</Anchor>.
</Text>
}
>
Outlook
</Checkbox>
</CheckboxGroup>
Component preview theme
<CheckboxDisclaimer id="disclaimer" value="disclaimer" name="disclaimer">
I declare the information provided above is accurate. I acknowledge that Twilio will process the information provided above for the purpose of identity verification, and will be sharing it with my local telecomm providers or authorities where required by local law. I understand that Twilio phone numbers may be taken out of service for inaccurate or false information.
</CheckboxDisclaimer>

To internationalize a checkbox, simply pass different text to the checkbox and checkbox group. The only exception to this is the required dot in the legend of a required checkbox group. To change the required dot's text, use the i18nRequiredLabel prop.

Component preview theme
<CheckboxGroup
name="days"
legend="Jours préférés"
i18nRequiredLabel="(requis)"
required
>
<Checkbox id="monday" value="monday">
lundi
</Checkbox>
<Checkbox id="tuesday" value="tuesday">
mardi
</Checkbox>
<Checkbox id="wednesday" value="wednesday">
mercredi
</Checkbox>
<Checkbox id="thursday" value="thursday">
jeudi
</Checkbox>
<Checkbox id="friday" value="friday">
vendredi
</Checkbox>
</CheckboxGroup>

Unchecked, checked and indeterminate

Unchecked, checked and indeterminate page anchor

The default state of a checkbox indicates that the control is unchecked, or not selected. When a checkbox is clicked or the spacebar is pressed when focused, the checkbox will become checked. Doing so again will place the checkbox back into the unchecked state. A checkbox can be placed into a pre-checked state by setting the checked property.

The third state a checkbox can appear in is the indeterminate state. This is to indicate that a checkbox is neither checked nor unchecked. This is useful when dealing with related groups of checkboxes that have a dependent relationship, for example, a select all feature.

Component preview theme
const Results = () => {
const [checkedItems, setCheckedItems] = React.useState([true, false]);
const allChecked = checkedItems.every(Boolean);
const indeterminate = checkedItems.some(Boolean) && !allChecked;
const checkboxRef = React.createRef();
return (
<CheckboxGroup isSelectAll name="results" legend="Include in Results">
<Checkbox
id="select_all"
checked={allChecked}
indeterminate={indeterminate}
ref={checkboxRef}
onChange={e => setCheckedItems([e.target.checked, e.target.checked])}
>
Select all
</Checkbox>
<Checkbox
id="identity"
checked={checkedItems[0]}
onChange={e => setCheckedItems([e.target.checked, checkedItems[1]])}
>
Identity carrier
</Checkbox>
<Checkbox
id="caller_name"
checked={checkedItems[1]}
onChange={e => setCheckedItems([checkedItems[0], e.target.checked])}
>
Caller name
</Checkbox>
</CheckboxGroup>
);
};
render(
<Results />
)

Use a disabled checkbox to indicate that a particular option cannot be interacted with or can be safely ignored.

Component preview theme
<Checkbox
id="hammer"
value="hammer"
name="hammer"
disabled
checked
>
Can't touch this
</Checkbox>

When at least one item from the checkbox group is required, a required indicator should be displayed alongside the group legend. The group help text should be used to describe the requirement.

Component preview theme
<CheckboxGroup
name="email"
legend="Email Notifications"
helpText="We can remind you when one of your Buffer is looking a little empty."
required
>
<Checkbox id="empty_buffer" value="empty_buffer">
Empty buffer
</Checkbox>
<Checkbox id="newsletter" value="newsletter">
Newsletter
</Checkbox>
<Checkbox id="update_failures" value="update_failures">
Update failures
</Checkbox>
</CheckboxGroup>

Use a disabled checkbox group to indicate that all options cannot be interacted with, with each checkbox individually disabled.

Component preview theme
<CheckboxGroup
name="capabilities"
legend="Capabilities"
orientation="horizontal"
disabled
>
<Checkbox id="voice" value="voice">
Voice
</Checkbox>
<Checkbox id="fax" value="fax">
Fax
</Checkbox>
<Checkbox id="sms" value="sms">
SMS
</Checkbox>
</CheckboxGroup>

Checkbox group with an inline error

Checkbox group with an inline error page anchor

If the selected options don't pass the group validation requirements, display an inline error message below the checkbox group.

Component preview theme
<CheckboxGroup
name="api"
legend="API Key Permissions"
errorText="Select at least one option."
>
<Checkbox id="full_access" value="full_access">
Full access
</Checkbox>
<Checkbox id="restricted_access" value="restricted_access">
Restricted access
</Checkbox>
</CheckboxGroup>

Checkbox labels, legends, and help text

Checkbox labels, legends, and help text page anchor

Checkboxes and Checkbox Groups must have a visible label.

  • Aim for no more than 3 words. If the label must be longer and space is limited, wrap the label.
  • Structure each checkbox label similarly. For example, make each checkbox a noun.
  • Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

Checkbox labels should reflect what happens if the box is checked. Avoid situations where the user must check a box to negate something. For example, "Don't send message."

Avoid constructing the legend and label text to read as a sentence.

Use Help Text to give additional context and provide enough information to avoid errors. Consider using Help Text to indicate to users that they can select multiple options. Limit Help Text to 1-2 sentences.

To support internationalization, avoid starting a sentence with the legend and using the field to finish it since sentence structures vary across languages. For example, use "Phone Number capabilities", not "Phone Number capabilities include:".

Validate form fields on form submission. Don't validate each item in a group, treat validation on the group as a whole.

Use inline error text to explain how to fix an error. Because space is typically limited, focus the error text on how users can fix the issue. For additional guidance on how to compose error messages, refer to the error state pattern.

Do

Use checkboxes to enable multiple choice.

Don't

Don't use checkboxes when you need to restrict selection to a single option. Use a Radio Group or Select instead.

Do

Save the choice the user made upon submission of the form.

Don't

Don't save or persist a user's choice upon checking a checkbox.

Do

Keep help text and error text concise and simple. If you need to use more than 2 sentences to explain a field, link out to supporting docs or trigger a popover instead.

Don't

Don't use more than 2 sentences in help text or error text.

Do

Include a visible label on every checkbox. Include a visible legend for the entire group of checkboxes.

Don't

Don't leave floating, unlabelled checkboxes.

Do

Write label text that clearly describes the value being requested.

Don't

Don't use the legend and label text in a way that is intended to be read as a sentence.

Do

Write legend text to describe a group and their intended relationship together.

Don't

Don't use a legend as a heading or section title.

Do

Provide actionable error text explaining how to fix the error.

Don't

Don't display system messages as error text or only what field errored.

Do

Use error text to explain how to resolve the error. For example, 'Accept the terms of agreement.'

Don't

Don’t focus on whether the field is required. For example, 'Accepting the terms of agreement is required.'