The Checkbox and Checkbox Group are used to enable binary choices

yarn add @twilio-paste/checkbox — or — yarn add @twilio-paste/core


Checkbox and Checkbox Group#

About Checkbox Group#

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 Information#

  • 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.

About Checkbox#

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 toggle switch component (being built in a coming sprint).

Accessibility Information#

  • 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 offending checkbox 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.


Basic checkbox with label#

A checkbox is always displayed next to a visible label.

Checkbox with help text#

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.

Determines if certificate validation is performed on all Twilio originated requests

Required 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.

Checkbox group#

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.

Select the clients you would like to test.

Checkbox group with help text#

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.

Which ad partnes would you like to advertise on?
Select at least 1 ad partner to create a campaign.
Questions? Click here to learn more.

Checkbox Disclaimer#


Unchecked, checked and indeterminate#

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.

Include in Results

Disabled checkbox#

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

Required checkbox group#

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.

Required: Email Notifications
We can remind yuou when one of your Buffer is looking a little empty.

Disabled checkbox group#

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


Checkbox group with an inline error#

If the selected options don't pass the group validation requirements, an inline error message should be displayed.

An inline error is placed at the top of the group to inform a user of any errors in their choices. If help text exists, the error text should replace and repeat the help text.

API Key Permissions
Please select at least one option.

Composition notes#

A checkbox must have a visible label.

Checkbox labels, legends and help text#

A checkbox must have a visible label. A checkbox group must have a visible legend.

Labels should clearly describe the value being requested. Legends should clearly describe the group. They should be concise and descriptive. To do this:

  • Use help text to provide additional context about the option if needed.
  • Avoid articles ("a", "the") and punctuation. For example, use "SIM registration code" rather than "The SIM registration code".

Give users enough information in help text to prevent an error. Keep it concise and scoped to information that will help with validation. For example, use help text if a particular option has a long description necessary to inform the users choice.

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:".

Validation and errors#

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.

Ideally, help text should have enough information to help users prevent errors. If help text exists and you need to show an error, the error text should replace and repeat the help text until the error has been resolved.

Error text should:

  • Be actionable. Explain how to fix an error and if reasonable, why it happened so that it might also be prevented in the future.
  • Be concise and simple, maybe even more than normal. Avoid jargon. Try to keep error text to 2 sentences or fewer.
  • Use the passive voice for input errors to avoid placing blame on the user. For example, "A Friendly Name is required."
  • Use the active voice for system errors. For example, "Our systems are currently down. Please contact our support team.".

When to use a Checkbox and Checkbox Group#

Use a checkbox when users are required to make a binary choice. Use a checkbox group when more than one checkbox is related to one another.

There is no maximum number of checkboxes you can have in a group, but when it starts to get over 6 you might consider another component. Use your discretion to decide what is best for your use case. Some alternatives to look at when the number of options starts getting above 6 might be a Select or Combobox.


Use checkboxes to enable multiple choice.


Don't use checkboxes when you need to restrict selection to a single option, use a radio group or select instead.


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


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


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 use more than 2 sentences in help text or error text.


Include a visible label on every checkbox


Don't leave floating, unlabelled checkboxes.


Write label text that clearly describes the value being requested.


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


Include a visible legend for the entire group of checkboxes.


Don't leave floating, unlabelled checkbox groups.


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


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


Provide actionable error text explaining how to fix the error.


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

Usage Guide#



yarn add @twilio-paste/checkbox - or - yarn add @twilio-paste/core


import {Checkbox, CheckboxGroup} from '@twilio-paste/checkbox';
const Component = () => (
<CheckboxGroup name="foo" legend="foo">
<Checkbox id="foo" value="foo" name="foo">

Checkbox Props#

All the valid HTML attributes for input[type=checkbox] are supported including the following props:

helpText?string or ReactNodenull
onChange?(event: React.MouseEvent<HTMLElement>)null
onFocus?(event: React.MouseEvent<HTMLElement>)null
onBlur?(event: React.MouseEvent<HTMLElement>)null

CheckboxGroup Props#

legendstring or ReactNodenull
orientationoneOf(['vertical', 'horizontal'])vertical
errorText?string or ReactNodenull
helpText?string or ReactNodenull

CheckboxDisclaimer Props#

All the valid HTML attributes for input[type=checkbox] are supported including the following props:

errorText?string or ReactNodenull
onChange?(event: React.MouseEvent<HTMLElement>)null
onFocus?(event: React.MouseEvent<HTMLElement>)null
onBlur?(event: React.MouseEvent<HTMLElement>)null


If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.


The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.