Checkbox (web component)

The checkbox component is composed of two custom elements: <bolt-checkbox-group> and <bolt-checkbox>:

<bolt-checkbox-group label="Group label goes here">
    <bolt-checkbox value="1">Item 1 label</bolt-checkbox>
    <bolt-checkbox value="2">Item 2 label</bolt-checkbox>
    <bolt-checkbox value="3">Item 3 label</bolt-checkbox>
</bolt-checkbox-group>

The bolt-checkbox-group component provides a wrapper around native <fieldset> and <legend> elements, applying a label (via the label attribute) to the set of bolt-checkbox components, which wrap native <input> and <label> elements and apply appropriate layout and data access APIs. The two components should be used together when multiple checkboxes are used. A single bolt-checkbox can also be used by itself.

The bolt-checkbox-group element must include one of these three parameters:

• label: The label text, used to populate the underlying <legend> element.
• arialabel: Sets the aria-label attribute of the underlying <input> element.
• arialabelledby: Sets the aria-labelledby attribute of the underlying <input> element.

Additionally, the bolt-checkbox-group element supports the following parameters:

• instructionaltext: optional. The instructional text to display below the label. This should be used to give users additional information about the checkbox group.
• required: optional. If not present, the group is marked as (optional). The required parameter should also be set at the bolt-checkbox level for any checkboxes in the group that require a response.
• optionaltext: optional. show (default) or hide. Use to remove the "(optional)" text from non-required fields.
• disabled: optional. If present, disables rendered interactive elements.
• error: optional. The error message to display.
  • Should not be used when component is disabled.
  • For slotted field error see checkbox error slot
• invalid: optional. If present, the group appears invalid.
• showtoggle : (optional): If present, displays the "Select all" / "Select none" option.
• bounded: optional. If present, all checkboxes in the group appear with a bounded border.

The <bolt-checkbox-group> element supports the use of bolt-contextual-help via the help slot placeholder. For more information and to see other options visit the contextual help page.

The <bolt-checkbox-group> custom element emits the following events:

• bolt-select-all: emitted when the 'select all' control is clicked.
• bolt-select-none: emitted when the 'select none' control is clicked.

The bolt-checkbox component supports the following attributes:

• name: optional. The form field's name attribute.
• value: required. The value of the checkbox button.
• disabled: optional. If present, disables rendered interactive elements.
• error: optional. The error message to display. Should only be used on a single checkbox when used outside of a bolt-checkbox-group.
  • Should not be used when component is disabled.
• checked: optional. If present, the control is checked.
• required: optional. If present, the required attribute is passed to the <input> element associated with that checkbox.
• arialabel: optional. An alternative label for screen reader usage that is not visible on the page. Screen readers will not read slotted content inside a bolt-checkbox element if arialabel is used.
• arialabelledby: optional. The id of an element containing label text for the input. It can accept multiple ids to point to other elements of the page using a space separated list. If arialabelledby is used, screen readers will not read slotted content inside a bolt-checkbox element or text from arialabel.
• invalid: optional. If present, the control appears invalid.
• datatestcheckbox optional property to configure the data-test value on the underlying <input> element. Default is checkbox.
• description: optional. Property adds descriptive text to an individual checkbox.
  • Must be plain text.
• bounded: optional. If present, checkbox appears with a bounded border.
  • If the checkbox is part of a group, bounded should be applied to <bolt-checkbox-group> instead.

• <bolt-checkbox>
  • [data-test="checkbox"] targets primary <input> element.
    • Configurable via the datatestcheckbox property

• Order individual Checkbox labels logically.
• Lengthy text may wrap.
• Checkbox group validation should occur upon submission of the parent form. Single Checkbox validation can occur after selecting the Checkbox or upon submission of the parent form.
• Checkbox group options should be stacked vertically.
• Consider using "select all" functionality in a Checkbox group based on context/content.
• Error messages should be displayed below a Checkbox group's legend or below the input and label of a single Checkbox.
• Avoid displaying more than one error message at a time. This can lead to user confusion.

• Consider a Checkbox when the user can select 0, 1, or multiple values from a predefined list.
• Consider a Checkbox when form submission is needed.
• Consider a single Checkbox for user confirmation, e.g., "I agree to…" or "I have read…".

• Avoid using Checkboxes for revealing or hiding other screen components.
• Avoid long lists of Checkboxes. Aim to keep the list to 7 options or under.

• Consider using a Switch for immediate actions that do not require reviewing or confirming.
• Consider a Radio button or a Select if users need to make a single, mutually-exclusive selection from two or more options.

• Write labels as statements that the checked state makes true, and the unchecked state makes false.
• Avoid using negative phrasing for labels.
• Use sentence case for Checkbox group labels and individual Checkbox labels.
• Ending punctuation is not needed for individual Checkbox labels.

• Each checkbox should be accessible via the Tab key.
• While focused, pressing Space should toggle between checked and unchecked.

• Safari + Voice over may not read descriptive text automatically and instead announce that more content is available.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.