Checkbox

BEEQ Checkbox component overview — Checkbox component overview

Checkboxes help people make independent selections, confirm agreement, or control optional settings. Use them when more than one option can be selected at the same time, or when a single opt-in needs an explicit checked state.

Every checkbox must have a visible label. Checkboxes that belong to the same decision should be grouped 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

Choose bq-switch instead of bq-checkbox when the setting takes effect immediately without a form submission, and bq-radio when users must choose exactly one option from a list. Keep consent and confirmation choices on bq-checkbox.

Patterns

Anatomy

A checkbox is composed of a visible label and a square control that can appear unselected, selected, or indeterminate depending on the current state.

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

Labels should start with the important words so people can scan the list quickly.

Group related choices

Checkboxes that belong to one decision or category should share a heading or fieldset.

Use indeterminate as a summary

Reserve the indeterminate state for parent checkboxes that represent a partially selected group.

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.

You do not need to set any prop that already uses its default value.

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

Allowed states: unchecked (default), checked, indeterminate. Setting indeterminate sets checked to false, and a user toggle clears indeterminate.

Background on hover

Use background-on-hover when the surrounding layout benefits from a larger perceived hit area and stronger hover feedback.

Checked and disabled

Use checked 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.

Indeterminate is a visual summary state, not a third submitted form value. Keep the parent and child checkboxes synchronized through event handling.

Form integration

bq-checkbox participates in native forms. A checked checkbox submits "on" for its name; an unchecked checkbox is omitted from FormData. Use required for consent or confirmation choices that must be selected before submission.

The live preview runs in an iframe sandbox that does not allow native form submission. Its Submit button uses type="button" and bqClick to validate the form and display FormData without submitting it. The copyable examples use native type="submit" buttons for normal application forms.

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 bqFocus and bqBlur when that input gains or loses focus.
Group related choices semantically — when multiple checkboxes form a set, they should share a heading or a <fieldset> with an accessible label.
Use indeterminate carefully — it should summarize a partial group selection and must not replace clear child options.
Do not rely on color alone — the checked mark, focus treatment, and label text together must communicate meaning; color must not be the only cue.

Keyboard interaction

Key	Context	Action
`Tab`	Checkbox enabled	Moves focus to the checkbox and emits `bqFocus`; focus leaving emits `bqBlur`
`Shift+Tab`	Checkbox enabled	Moves focus to the previous focusable element
`Space`	Checkbox focused	Toggles the checked state through the native input and emits `bqChange`
`Tab`	Checkbox disabled	Skips the checkbox

Rules

Rule	Strength	Verified by
Provide a visible label in the default slot	MUST	manual: inspect the visible label beside the checkbox
Set `name` so the checked state is submitted with the form	MUST	automated: `bq-checkbox.e2e.tsx` checks `FormData`
Set `required` on checkboxes that must be checked before submission	MUST	automated: `bq-checkbox.e2e.tsx` checks `form.checkValidity()`
Set `form-validation-message` on required checkboxes to give a specific validation message	SHOULD	manual: inspect the required-field message in a form
Keep the parent and child checkboxes synchronized in a nested group	MUST	manual: toggle parent and child items and compare their states
Use `indeterminate` only to summarize a partially selected group	SHOULD	manual: check indeterminate only appears for partial selection
Group related checkboxes under a shared heading or `<fieldset>`	SHOULD	manual: inspect the shared heading or fieldset for a related group
Use more than color to communicate the checked state	MUST	manual: read the checked state without relying on color

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`	Sets the underlying `<input>` value attribute. The current form submission value is the fixed string `'on'` when checked	`string`	`undefined`

Invalid combinations

Combination	Strength	Result
`indeterminate` set while `checked` is `true`	SHOULD NOT	`checked` is set to `false`

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

Hide CSS variables

Variable	Description	Default
`--bq-checkbox--background-color`	Checkbox background color	`var(--bq-ui--primary)`
`--bq-checkbox--background-color-checked`	Checkbox background color when checked or indeterminate	`var(--bq-ui--brand)`
`--bq-checkbox--border-color`	Checkbox border color	`var(--bq-stroke--tertiary)`
`--bq-checkbox--border-color-checked`	Checkbox border color when checked or indeterminate	`var(--bq-ui--brand)`
`--bq-checkbox--icon-color-checked`	Checkbox check and indeterminate mark color	`var(--bq-text--on-brand)`
`--bq-checkbox--label-text-color`	Checkbox label text color	`var(--bq-text--primary)`
`--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)`

Learn more about styling with shadow parts and CSS custom properties.

Resources

Interactive playground

Explore checkbox examples and states in Storybook

Source code

View the component source on GitHub

Actions

Data Display

Feedback

Form Controls

Layout

Navigation

When to use

Patterns

Anatomy

Design guidelines

Usage

Default

Long label

Options

Background on hover

Checked and disabled

Indeterminate group

Form integration

Best practices

Accessibility

Keyboard interaction

Rules

API reference

Properties

Invalid combinations

Events

Methods

Slots

Shadow parts

CSS custom properties

Resources

Interactive playground

Source code

​When to use

​Patterns

​Anatomy

​Design guidelines

​Usage

​Default

​Long label

​Options

​Background on hover

​Checked and disabled

​Indeterminate group

​Form integration

​Best practices

​Accessibility

​Keyboard interaction

​Rules

​API reference

​Properties

​Invalid combinations

​Events

​Methods

​Slots

​Shadow parts

​CSS custom properties

​Resources

Interactive playground

Source code

When to use

Patterns

Anatomy

Design guidelines

Usage

Default

Long label

Options

Background on hover

Checked and disabled

Indeterminate group

Form integration

Best practices

Accessibility

Keyboard interaction

Rules

API reference

Properties

Invalid combinations

Events

Methods

Slots

Shadow parts

CSS custom properties

Resources