Use a clear visible label for every checkbox. When several checkboxes belong to the same decision, group them under a shared descriptive heading.
When to use
Use checkboxes when
- People can select one, many, or none from a set of options
- A setting or preference needs a simple on or off choice
- A form needs explicit confirmation, such as accepting terms
Do not use checkboxes when
- The user must choose exactly one option from a list
- An action should happen immediately instead of storing a selected state
- The label is so long or ambiguous that the yes-or-no meaning becomes unclear
Patterns
Anatomy
| Part | Element | Description |
|---|---|---|
| 1 | Label | The text that explains the option or setting and makes the checked state understandable |
| 2 | Checkbox: default | The square control in its unchecked state before selection |
| 3 | Checkbox: active | The selected or indeterminate state that confirms the option is enabled or partially selected |
Design guidelines
Use checkbox labels and grouping patterns that make the selected state easy to understand before people interact with the control.Start with the key meaning
Put the important words at the beginning of the label so people can scan the list quickly.
Group related choices
Use a shared heading or fieldset when several checkboxes belong to one decision or category.
If users must choose exactly one option, use Radio instead of adapting a checkbox pattern to a single-select task.
Usage
Default
Use the default checkbox for a straightforward binary choice with a short label.Long label
Use a longer label when people need more context before deciding, but keep the core meaning easy to scan at the beginning of the sentence.Options
Background on hover
Usebackground-on-hover when the surrounding layout benefits from a larger perceived hit area and stronger hover feedback.
Checked and disabled
Usechecked for a preselected default, and disabled when the option is currently unavailable or not editable in the current context.
Indeterminate group
Use the indeterminate state when a parent checkbox controls a related set of child options and only some of them are selected.Best practices
DoWrite checkbox labels as clear statements, not questions, so people understand the resulting selected state.
Don’tDo not use checkboxes when users must choose only one option. Use Radio instead.
DoAlign long labels from the top so wrapped text stays visually connected to the checkbox control.
Don’tDo not center long wrapped labels vertically against the control, because that weakens scanability.
DoGroup related checkboxes under a shared heading when they belong to the same decision.
Don’tDo not rely on unchecked-by-default choices to imply consent when legal or high-stakes confirmation is required.
DoUse the indeterminate state only when it accurately summarizes a partially selected group of child options.
Don’tDo not present indeterminate as a standalone third choice, because it is only meaningful as a group summary.
Accessibility
- Built-in native checkbox semantics — the component uses a native
<input type="checkbox">, so checked, unchecked, disabled, and required states follow standard browser and assistive technology behavior. - Built-in label association — the internal input and the slotted text are wrapped in the same
<label>, so clicking the label toggles the checkbox without extra wiring. - Built-in focus support — the shadow root delegates focus to the native input, and the component emits
bqFocusandbqBlurwhen that input gains or loses focus. - Group related choices semantically — when multiple checkboxes form a set, provide a shared heading or a
<fieldset>with an accessible label. - Use indeterminate carefully — it should summarize a partial group selection, not replace clear child options.
- Do not rely on color alone — the checked mark, focus treatment, and label text should all help communicate meaning.
API reference
Properties
| Property | Attribute | Description | Type | Default |
|---|---|---|---|---|
backgroundOnHover | background-on-hover | If true, the checkbox displays a background on hover | boolean | false |
checked | checked | If true, the checkbox is checked | boolean | undefined |
disabled | disabled | If true, the checkbox is disabled | boolean | false |
formId | form-id | The form ID that the checkbox is associated with | string | undefined |
formValidationMessage | form-validation-message | The native form validation message | string | undefined |
indeterminate | indeterminate | A state that is neither checked nor unchecked | boolean | false |
name | name | Name of the HTML form control submitted with the form | string | undefined |
required | required | If true, the checkbox must be selected before form submission | boolean | undefined |
value | value | The submitted value for the checkbox | string | undefined |
Events
| Event | Description | Type |
|---|---|---|
bqBlur | Fired when the checkbox loses focus | CustomEvent<HTMLBqCheckboxElement> |
bqChange | Fired when the checkbox state changes | CustomEvent<{ checked: boolean; }> |
bqFocus | Fired when the checkbox receives focus | CustomEvent<HTMLBqCheckboxElement> |
Methods
| Method | Description | Returns |
|---|---|---|
vBlur() | Removes focus from the native input element | Promise<void> |
vClick() | Simulates a click on the native input element | Promise<void> |
vFocus() | Sets focus on the native input element | Promise<void> |
Slots
| Slot | Description |
|---|---|
| (default) | The visible label content for the checkbox |
Shadow parts
| Part | Description |
|---|---|
base | The component’s internal wrapper |
control | The container that holds the custom checkbox |
input | The native <input type="checkbox"> used under the hood |
checkbox | The element that renders the checked or indeterminate state |
label | The element that holds the text content |
CSS custom properties
| Variable | Description | Default |
|---|---|---|
--bq-checkbox--size | Checkbox size | 24px |
--bq-checkbox--border-radius | Checkbox border radius | var(--bq-radius--xs) |
--bq-checkbox--border-width | Checkbox border width | var(--bq-stroke-m) |
Resources
Interactive playground
Explore checkbox examples and states in Storybook
Source code
View the component source on GitHub