> ## Documentation Index
> Fetch the complete documentation index at: https://www.beeq.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkbox

> Checkboxes let people select one or more independent options, or confirm a single yes-or-no choice.

![BEEQ Checkbox component overview](https://mintcdn.com/beeq/nN2FF5Iq6pY7AHlL/components/images/checkbox/checkbox-overview-light.svg?fit=max\&auto=format\&n=nN2FF5Iq6pY7AHlL\&q=85\&s=0429705e75879f0047407793b0344696)

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.

> [!NOTE]
>
> 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

> [card]
>
> 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

> [card]
>
> 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

> [!TIP]
>
> Choose [`bq-switch`](https://www.beeq.design/components/switch) instead of `bq-checkbox` when the setting takes effect immediately without a form submission, and [`bq-radio`](https://www.beeq.design/components/radio) when users must choose exactly one option from a list. Keep consent and confirmation choices on `bq-checkbox`.

## Patterns

![Single](https://www.beeq.design/components/images/checkbox/checkbox-pattern-single-light.svg)
![Single](https://www.beeq.design/components/images/checkbox/checkbox-pattern-single-dark.svg)

## Single

Use a single checkbox for one independent yes-or-no decision, such as subscribing to updates or accepting terms.

![Group](https://www.beeq.design/components/images/checkbox/checkbox-pattern-group-light.svg)
![Group](https://www.beeq.design/components/images/checkbox/checkbox-pattern-group-dark.svg)

## Group

Use a checkbox group when several related options can be selected together and none of them are mutually exclusive.

![Nesting](https://www.beeq.design/components/images/checkbox/checkbox-pattern-nesting-light.svg)
![Nesting](https://www.beeq.design/components/images/checkbox/checkbox-pattern-nesting-dark.svg)

## Nesting

Use a parent checkbox when one control should select or clear a related set of child checkboxes.

![Indeterminate state](https://www.beeq.design/components/images/checkbox/checkbox-pattern-indeterminate-light.svg)
![Indeterminate state](https://www.beeq.design/components/images/checkbox/checkbox-pattern-indeterminate-dark.svg)

## Indeterminate state

Use the indeterminate state when a parent checkbox needs to show that only some child options are selected.

## Anatomy

![BEEQ Checkbox component anatomy](https://mintcdn.com/beeq/nN2FF5Iq6pY7AHlL/components/images/checkbox/checkbox-anatomy-light.svg?fit=max\&auto=format\&n=nN2FF5Iq6pY7AHlL\&q=85\&s=3f827a09942de00a045831ade98776d2)

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 labels as outcomes

The label should read as a clear statement of the checked state, especially in settings and consent flows.

## Make hierarchy obvious

When a parent checkbox controls child options, make the relationship visually clear and keep the parent state synchronized.

**1. Start with the key meaning**

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

**2. Group related choices**

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

**3. Use indeterminate as a summary**

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

> [!NOTE]
>
> If users must choose exactly one option, use [Radio](https://www.beeq.design/components/radio.md) 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.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-checkbox name="updates" value="updates">
  Send me product updates
</bq-checkbox>
```

```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqCheckbox } from "@beeq/react";

<BqCheckbox name="updates" value="updates">
  Send me product updates
</BqCheckbox>
```

```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: `
    <bq-checkbox name="updates" value="updates">
      Send me product updates
    </bq-checkbox>
  `
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqCheckbox } from "@beeq/vue";
</script>

<template>
  <BqCheckbox name="updates" value="updates">
    Send me product updates
  </BqCheckbox>
</template>
```

> [!TIP]
>
> 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.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-checkbox name="terms" value="terms">
  By clicking here, I state that I have read and understood the terms and conditions.
</bq-checkbox>
```

```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqCheckbox } from "@beeq/react";

<BqCheckbox name="terms" value="terms">
  By clicking here, I state that I have read and understood the terms and conditions.
</BqCheckbox>
```

```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: `
    <bq-checkbox name="terms" value="terms">
      By clicking here, I state that I have read and understood the terms and conditions.
    </bq-checkbox>
  `
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqCheckbox } from "@beeq/vue";
</script>

<template>
  <BqCheckbox name="terms" value="terms">
    By clicking here, I state that I have read and understood the terms and conditions.
  </BqCheckbox>
</template>
```

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

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-checkbox name="notifications" value="notifications" background-on-hover>
  Email me about account activity
</bq-checkbox>
```

```jsx React icon="react" theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqCheckbox } from "@beeq/react";

<BqCheckbox name="notifications" value="notifications" backgroundOnHover>
  Email me about account activity
</BqCheckbox>
```

```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: `
    <bq-checkbox name="notifications" value="notifications" background-on-hover>
      Email me about account activity
    </bq-checkbox>
  `
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqCheckbox } from "@beeq/vue";
</script>

<template>
  <BqCheckbox name="notifications" value="notifications" backgroundOnHover>
    Email me about account activity
  </BqCheckbox>
</template>
```

### Checked and disabled

Use `checked` for a preselected default, and `disabled` when the option is currently unavailable or not editable in the current context.

```html HTML icon="html5" theme={"theme":{"light":"one-light","dark":"night-owl"}}
<bq-checkbox checked name="newsletter" value="newsletter">
  Subscribe to the newsletter
</bq-checkbox>
<bq-checkbox disabled name="archived" value="archived">
  Archived option
</bq-checkbox>
```

```jsx React icon="react" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
import { BqCheckbox } from "@beeq/react";

<BqCheckbox checked name="newsletter" value="newsletter">
  Subscribe to the newsletter
</BqCheckbox>
<BqCheckbox disabled name="archived" value="archived">
  Archived option
</BqCheckbox>
```

```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: `
    <bq-checkbox checked name="newsletter" value="newsletter">
      Subscribe to the newsletter
    </bq-checkbox>
    <bq-checkbox disabled name="archived" value="archived">
      Archived option
    </bq-checkbox>
  `
})
export class AppComponent {}
```

```vue Vue icon="vuejs" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<script setup lang="ts">
import { BqCheckbox } from "@beeq/vue";
</script>

<template>
  <BqCheckbox checked name="newsletter" value="newsletter">
    Subscribe to the newsletter
  </BqCheckbox>
  <BqCheckbox disabled name="archived" value="archived">
    Archived option
  </BqCheckbox>
</template>
```

### Indeterminate group

Use the indeterminate state when a parent checkbox controls a related set of child options and only some of them are selected.

```js JavaScript icon="js" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
(() => {
  customElements.whenDefined('bq-checkbox').then(() => {
    const checkboxGroup = document.querySelector('.checkbox-group');
    const allInterestCheckbox = checkboxGroup.querySelector('bq-checkbox[name="all-interests"]');
    const interestCheckboxes = Array.from(checkboxGroup.querySelectorAll('bq-checkbox[name="interest"]'));

    const syncParentCheckbox = () => {
      const checkedCount = interestCheckboxes.filter((checkbox) => checkbox.checked).length;
      allInterestCheckbox.indeterminate =
        checkedCount > 0 && checkedCount < interestCheckboxes.length;
      allInterestCheckbox.checked = checkedCount === interestCheckboxes.length;
    };

    const syncChildrenCheckboxes = (event) => {
      interestCheckboxes.forEach((checkbox) => {
        checkbox.checked = event.detail.checked;
      });
      allInterestCheckbox.indeterminate = false;
    };

    syncParentCheckbox();
    allInterestCheckbox.addEventListener('bqChange', syncChildrenCheckboxes);
    interestCheckboxes.forEach((checkbox) => {
      checkbox.addEventListener('bqChange', syncParentCheckbox);
    });
  });
})();
```

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<div class="checkbox-group">
  <bq-checkbox name="all-interests" value="all" background-on-hover>
    Interests
  </bq-checkbox>

  <div class="checkbox-group__children">
    <bq-checkbox checked name="interest" value="music" background-on-hover>
      Music
    </bq-checkbox>
    <bq-checkbox name="interest" value="travel" background-on-hover>
      Travel
    </bq-checkbox>
    <bq-checkbox checked name="interest" value="sport" background-on-hover>
      Sport
    </bq-checkbox>
  </div>
</div>
```

```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 (
    <div className="checkbox-group">
      <BqCheckbox
        backgroundOnHover
        checked={allChecked}
        indeterminate={isIndeterminate}
        name="all-interests"
        value="all"
        onBqChange={(event) => setAllInterests(event.detail.checked)}
      >
        Interests
      </BqCheckbox>

      <div className="checkbox-group__children">
        <BqCheckbox
          backgroundOnHover
          checked={interests.music}
          name="interest"
          value="music"
          onBqChange={(event) =>
            setInterests((current) => ({ ...current, music: event.detail.checked }))
          }
        >
          Music
        </BqCheckbox>
        <BqCheckbox
          backgroundOnHover
          checked={interests.travel}
          name="interest"
          value="travel"
          onBqChange={(event) =>
            setInterests((current) => ({ ...current, travel: event.detail.checked }))
          }
        >
          Travel
        </BqCheckbox>
        <BqCheckbox
          backgroundOnHover
          checked={interests.sport}
          name="interest"
          value="sport"
          onBqChange={(event) =>
            setInterests((current) => ({ ...current, sport: event.detail.checked }))
          }
        >
          Sport
        </BqCheckbox>
      </div>
    </div>
  );
}
```

```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: `
    <div class="checkbox-group">
      <bq-checkbox
        background-on-hover
        [checked]="allChecked"
        [indeterminate]="isIndeterminate"
        name="all-interests"
        value="all"
        (bqChange)="setAllInterests($event.detail.checked)"
      >
        Interests
      </bq-checkbox>

      <div class="checkbox-group__children">
        <bq-checkbox
          background-on-hover
          [checked]="interests.music"
          name="interest"
          value="music"
          (bqChange)="setInterest('music', $event.detail.checked)"
        >
          Music
        </bq-checkbox>
        <bq-checkbox
          background-on-hover
          [checked]="interests.travel"
          name="interest"
          value="travel"
          (bqChange)="setInterest('travel', $event.detail.checked)"
        >
          Travel
        </bq-checkbox>
        <bq-checkbox
          background-on-hover
          [checked]="interests.sport"
          name="interest"
          value="sport"
          (bqChange)="setInterest('sport', $event.detail.checked)"
        >
          Sport
        </bq-checkbox>
      </div>
    </div>
  `,
})
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"}}
<script setup lang="ts">
import { computed, reactive } from "vue";
import { BqCheckbox } from "@beeq/vue";

const interests = reactive({
  music: true,
  travel: false,
  sport: true,
});

const values = computed(() => Object.values(interests));
const allChecked = computed(() => values.value.every(Boolean));
const isIndeterminate = computed(() => values.value.some(Boolean) && !allChecked.value);

const setAllInterests = (checked: boolean) => {
  interests.music = checked;
  interests.travel = checked;
  interests.sport = checked;
};
</script>

<template>
  <div class="checkbox-group">
    <BqCheckbox
      backgroundOnHover
      :checked="allChecked"
      :indeterminate="isIndeterminate"
      name="all-interests"
      value="all"
      @bqChange="setAllInterests($event.detail.checked)"
    >
      Interests
    </BqCheckbox>

    <div class="checkbox-group__children">
      <BqCheckbox
        backgroundOnHover
        :checked="interests.music"
        name="interest"
        value="music"
        @bqChange="interests.music = $event.detail.checked"
      >
        Music
      </BqCheckbox>
      <BqCheckbox
        backgroundOnHover
        :checked="interests.travel"
        name="interest"
        value="travel"
        @bqChange="interests.travel = $event.detail.checked"
      >
        Travel
      </BqCheckbox>
      <BqCheckbox
        backgroundOnHover
        :checked="interests.sport"
        name="interest"
        value="sport"
        @bqChange="interests.sport = $event.detail.checked"
      >
        Sport
      </BqCheckbox>
    </div>
  </div>
</template>
```

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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.

```html HTML icon="html5" expandable theme={"theme":{"light":"one-light","dark":"night-owl"}}
<form id="checkbox-form">
  <bq-checkbox
    form-validation-message="Accept the terms to continue"
    name="termsAccepted"
    required
  >
    By clicking here, I state that I have read and understood the terms and conditions
  </bq-checkbox>
  <bq-button appearance="secondary" type="reset">Reset</bq-button>
  <bq-button type="submit">Submit</bq-button>
  <pre id="checkbox-output">{}</pre>
</form>

<script>
  const form = document.querySelector('#checkbox-form');
  const output = document.querySelector('#checkbox-output');

  form.addEventListener('submit', (event) => {
    event.preventDefault();
    output.textContent = JSON.stringify(Object.fromEntries(new FormData(form).entries()), null, 2);
  });

  form.addEventListener('reset', () => {
    requestAnimationFrame(() => {
      output.textContent = '{}';
    });
  });
</script>
```

```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 (
    <form
      onReset={() => setData("{}")}
      onSubmit={(event) => {
        event.preventDefault();
        setData(JSON.stringify(Object.fromEntries(new FormData(event.currentTarget).entries()), null, 2));
      }}
    >
      <BqCheckbox
        formValidationMessage="Accept the terms to continue"
        name="termsAccepted"
        required
      >
        By clicking here, I state that I have read and understood the terms and conditions
      </BqCheckbox>
      <BqButton appearance="secondary" type="reset">Reset</BqButton>
      <BqButton type="submit">Submit</BqButton>
      <pre>{data}</pre>
    </form>
  );
}
```

```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: `
    <form (reset)="data = '{}'" (submit)="handleSubmit($event)">
      <bq-checkbox
        form-validation-message="Accept the terms to continue"
        name="termsAccepted"
        required
      >
        By clicking here, I state that I have read and understood the terms and conditions
      </bq-checkbox>
      <bq-button appearance="secondary" type="reset">Reset</bq-button>
      <bq-button type="submit">Submit</bq-button>
      <pre>{{ data }}</pre>
    </form>
  `,
})
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"}}
<script setup lang="ts">
import { ref } from "vue";
import { BqButton, BqCheckbox } from "@beeq/vue";

const data = ref("{}");

function handleSubmit(event: Event) {
  data.value = JSON.stringify(Object.fromEntries(new FormData(event.target as HTMLFormElement).entries()), null, 2);
}
</script>

<template>
  <form @reset="data = '{}'" @submit.prevent="handleSubmit">
    <BqCheckbox
      formValidationMessage="Accept the terms to continue"
      name="termsAccepted"
      required
    >
      By clicking here, I state that I have read and understood the terms and conditions
    </BqCheckbox>
    <BqButton appearance="secondary" type="reset">Reset</BqButton>
    <BqButton type="submit">Submit</BqButton>
    <pre>{{ data }}</pre>
  </form>
</template>
```

## Best practices

> [card]
>
> Do
>
> Write checkbox labels as clear statements, not questions, so people understand the resulting selected state.

> [card]
>
> Don't
>
> Do not use checkboxes when users must choose only one option. Use [Radio](https://www.beeq.design/components/radio.md) instead.

> [card]
>
> Do
>
> Align long labels from the top so wrapped text stays visually connected to the checkbox control.

> [card]
>
> Don't
>
> Do not center long wrapped labels vertically against the control, because that weakens scanability.

> [card]
>
> Do
>
> Group related checkboxes under a shared heading when they belong to the same decision.

> [card]
>
> Don't
>
> Do not rely on unchecked-by-default choices to imply consent when legal or high-stakes confirmation is required.

> [card]
>
> Do
>
> Use the indeterminate state only when it accurately summarizes a partially selected group of child options.

> [card]
>
> 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 `<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`](https://github.com/Endava/BEEQ/blob/main/packages/beeq/src/components/checkbox/__tests__/bq-checkbox.e2e.tsx) checks `FormData` |
| Set `required` on checkboxes that must be checked before submission | MUST | automated: [`bq-checkbox.e2e.tsx`](https://github.com/Endava/BEEQ/blob/main/packages/beeq/src/components/checkbox/__tests__/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

**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)` |

> [!TIP]
>
> Learn more about [styling with shadow parts](https://www.beeq.design/guides/styles.md#component-shadow-dom-parts) and [CSS custom properties](https://www.beeq.design/guides/styles.md#global-css-custom-properties).

## Resources

> [card] [Interactive playground](https://storybook.beeq.design/?path=/story/components-checkbox--default)
>
> Explore checkbox examples and states in Storybook

> [card] [Source code](https://github.com/Endava/BEEQ/tree/main/packages/beeq/src/components/checkbox)
>
> View the component source on GitHub


## Related topics

- [Option](https://www.beeq.design/components/option.md)
- [Select](https://www.beeq.design/components/select.md)
- [Switch](https://www.beeq.design/components/switch.md)
- [Radio](https://www.beeq.design/components/radio.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.