Skip to main content
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.
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

BEEQ Checkbox component anatomy

Checkbox component 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.

​
Design guidelines

Use checkbox labels and grouping patterns that make the selected state easy to understand before people interact with the control.
1

Start with the key meaning

Put the important words at the beginning of the label so people can scan the list quickly.
2

Group related choices

Use a shared heading or fieldset when several checkboxes belong to one decision or category.
3

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

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

​
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, 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

​
Events

​
Methods

​
Slots

​
Shadow parts

​
CSS custom properties

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