{}

{} {children &&

{children}

}

; }; export const CardTile = ({title, href, imageLightSrc, imageDarkSrc, children, enableImgZoom}) => { if (!href) { return

{imageLightSrc && {title}

} {imageDarkSrc && {title}

} {title &&

{title}

}

{children}

; } return {imageLightSrc && {title}

} {imageDarkSrc && {title}

} {title &&

{title}

}

{children}

; };

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 Use a single checkbox for one independent yes-or-no decision, such as subscribing to updates or accepting terms. Use a checkbox group when several related options can be selected together and none of them are mutually exclusive. Use a parent checkbox when one control should select or clear a related set of child checkboxes. Use the indeterminate state when a parent checkbox needs to show that only some child options are selected. ## Anatomy BEEQ 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. | 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. Write the label so the checked state reads like a clear statement, especially in settings and consent flows. When a parent checkbox controls child options, make the relationship visually clear and keep the parent state synchronized. Put the important words at the beginning of the label so people can scan the list quickly. Use a shared heading or fieldset when several checkboxes belong to one decision or category. Reserve the indeterminate state for parent checkboxes that represent a partially selected group. If users must choose exactly one option, use [Radio](/components/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. Send me product updates `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Send me product updates ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqCheckbox } from "@beeq/react"; Send me product updates ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqCheckbox } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqCheckbox], template: ` Send me product updates ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` 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. .checkbox-long { max-inline-size: 18rem; } By clicking here, I state that I have read and understood the terms and conditions. `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} By clicking here, I state that I have read and understood the terms and conditions. ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqCheckbox } from "@beeq/react"; By clicking here, I state that I have read and understood the terms and conditions. ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqCheckbox } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqCheckbox], template: ` By clicking here, I state that I have read and understood the terms and conditions. ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Options ### Background on hover Use `background-on-hover` when the surrounding layout benefits from a larger perceived hit area and stronger hover feedback. Email me about account activity `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Email me about account activity ``` ```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqCheckbox } from "@beeq/react"; Email me about account activity ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqCheckbox } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqCheckbox], template: ` Email me about account activity ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Checked and disabled Use `checked` for a preselected default, and `disabled` when the option is currently unavailable or not editable in the current context. Subscribe to the newsletter Archived option `} > ```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}} Subscribe to the newsletter Archived option ``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { BqCheckbox } from "@beeq/react"; Subscribe to the newsletter Archived option ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqCheckbox } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqCheckbox], template: ` Subscribe to the newsletter Archived option ` }) export class AppComponent {} ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ### Indeterminate group Use the indeterminate state when a parent checkbox controls a related set of child options and only some of them are selected. .checkbox-group__children { display: flex; flex-direction: column; gap: var(--bq-spacing-xs2); margin-inline-start: 1.5rem; }

Interests

Music

Travel

Sport

`} > ```js JavaScript icon="js" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} const allCheckboxChange = (event) => { const interestCheckboxes = Array.from( previewRoot.querySelectorAll('bq-checkbox[name="interest"]'), ); interestCheckboxes.forEach((interestCheckbox) => { interestCheckbox.checked = event.detail.checked; }); }; const interestCheckboxChange = () => { const allInterestCheckbox = previewRoot.querySelector('bq-checkbox[name="all-interests"]'); if (!allInterestCheckbox) return; const interestCheckboxes = previewRoot.querySelectorAll('bq-checkbox[name="interest"]'); const onlyChecked = previewRoot.querySelectorAll( 'bq-checkbox[name="interest"][checked]', ).length; allInterestCheckbox.indeterminate = onlyChecked > 0 && onlyChecked < interestCheckboxes.length; allInterestCheckbox.checked = onlyChecked === interestCheckboxes.length; }; const allInterestCheckbox = previewRoot.querySelector('bq-checkbox[name="all-interests"]'); const interestCheckboxes = Array.from( previewRoot.querySelectorAll('bq-checkbox[name="interest"]'), ); allInterestCheckbox?.addEventListener('bqChange', allCheckboxChange); interestCheckboxes.forEach((checkbox) => { checkbox.addEventListener('bqChange', interestCheckboxChange); }); interestCheckboxChange(); ``` ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

Interests

Music

Travel

Sport

``` ```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useState } from "react"; import { BqCheckbox } from "@beeq/react"; export function IndeterminateCheckboxGroup() { const [interests, setInterests] = useState({ music: true, travel: false, sport: true, }); const values = Object.values(interests); const allChecked = values.every(Boolean); const isIndeterminate = values.some(Boolean) && !allChecked; const setAllInterests = (checked) => { setInterests({ music: checked, travel: checked, sport: checked, }); }; return (

setAllInterests(event.detail.checked)} > Interests

setInterests((current) => ({ ...current, music: event.detail.checked })) } > Music setInterests((current) => ({ ...current, travel: event.detail.checked })) } > Travel setInterests((current) => ({ ...current, sport: event.detail.checked })) } > Sport

); } ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqCheckbox } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqCheckbox], template: `

Interests

Music

Travel

Sport

`, }) export class AppComponent { interests = { music: true, travel: false, sport: true }; get allChecked() { return Object.values(this.interests).every(Boolean); } get isIndeterminate() { const values = Object.values(this.interests); return values.some(Boolean) && !values.every(Boolean); } setAllInterests(checked: boolean) { this.interests = { music: checked, travel: checked, sport: checked }; } setInterest(key: 'music' | 'travel' | 'sport', checked: boolean) { this.interests = { ...this.interests, [key]: checked }; } } ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` 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. body { padding: var(--bq-spacing-l); } .checkbox-form { display: grid; gap: var(--bq-spacing-m); } .checkbox-form__actions { display: flex; gap: var(--bq-spacing-s); justify-content: flex-end; } .checkbox-form__output { margin: 0; padding: var(--bq-spacing-s); border: var(--bq-stroke-s) solid var(--bq-stroke--tertiary); border-radius: var(--bq-radius--s); background: var(--bq-ui--secondary); color: var(--bq-text--primary); white-space: pre-wrap; }

By clicking here, I state that I have read and understood the terms and conditions

Cancel

Submit

{}

`} > ```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}

By clicking here, I state that I have read and understood the terms and conditions

Reset

Submit

{}

``` ```tsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { useState } from "react"; import { BqButton, BqCheckbox } from "@beeq/react"; export default function CheckboxForm() { const [data, setData] = useState("{}"); return (

setData("{}")} onSubmit={(event) => { event.preventDefault(); setData(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget).entries()), null, 2)); }} > By clicking here, I state that I have read and understood the terms and conditions Reset Submit

{data}

); } ``` ```ts Angular icon="angular" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} import { Component } from "@angular/core"; import { BqButton, BqCheckbox } from "@beeq/angular/standalone"; @Component({ selector: "app-root", standalone: true, imports: [BqButton, BqCheckbox], template: `

By clicking here, I state that I have read and understood the terms and conditions

Reset

Submit

{{ data }}

`, }) export class CheckboxFormComponent { data = "{}"; handleSubmit(event: SubmitEvent): void { event.preventDefault(); this.data = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2); } } ``` ```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}} ``` ## Best practices Do Write checkbox labels as clear statements, not questions, so people understand the resulting selected state. Don't Do not use checkboxes when users must choose only one option. Use [Radio](/components/radio) instead. Do Align long labels from the top so wrapped text stays visually connected to the checkbox control. Don't Do not center long wrapped labels vertically against the control, because that weakens scanability. Do Group related checkboxes under a shared heading when they belong to the same decision. Don't Do not rely on unchecked-by-default choices to imply consent when legal or high-stakes confirmation is required. Do Use the indeterminate state only when it accurately summarizes a partially selected group of child options. Don't Do 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 ``, 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 ``, 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 `

` 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` | Sets the underlying `` value attribute. The current form submission value is the fixed string `'on'` when checked | `string` | `undefined` | ### Events | Event | Description | Type | | ---------- | -------------------------------------- | ------------------------------------ | | `bqBlur` | Fired when the checkbox loses focus | `CustomEvent` | | `bqChange` | Fired when the checkbox state changes | `CustomEvent<{ checked: boolean; }>` | | `bqFocus` | Fired when the checkbox receives focus | `CustomEvent` | ### Methods | Method | Description | Returns | | ---------- | --------------------------------------------- | --------------- | | `vBlur()` | Removes focus from the native input element | `Promise` | | `vClick()` | Simulates a click on the native input element | `Promise` | | `vFocus()` | Sets focus on the native input element | `Promise` | ### 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 `` 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)` | Learn more about [styling with shadow parts](/guides/styles#component-shadow-dom-parts) and [CSS custom properties](/guides/styles#global-css-custom-properties). ## Resources Explore checkbox examples and states in Storybook View the component source on GitHub