## Overview `` allow users to select multiple items from a list of independent options, or to mark an individual option as selected. Should I use a checkbox or a switch? Use a switch when activating something instead of selecting. ### Usage [![See it on NPM!](https://img.shields.io/npm/v/@spectrum-web-components/checkbox?style=for-the-badge)](https://www.npmjs.com/package/@spectrum-web-components/checkbox) [![How big is this package in your project?](https://img.shields.io/bundlephobia/minzip/@spectrum-web-components/checkbox?style=for-the-badge)](https://bundlephobia.com/result?p=@spectrum-web-components/checkbox) [![Try it on Stackblitz](https://img.shields.io/badge/Try%20it%20on-Stackblitz-blue?style=for-the-badge)](https://stackblitz.com/edit/vitejs-vite-31hvwr2m) ```bash yarn add @spectrum-web-components/checkbox ``` Import the side effectful registration of `` via: ```ts import '@spectrum-web-components/checkbox/sp-checkbox.js'; ``` When looking to leverage the `Checkbox` base class as a type and/or for extension purposes, do so via: ```ts import { Checkbox } from '@spectrum-web-components/checkbox'; ``` ### Anatomy A checkbox consists of a box that can be checked or unchecked, and a label that describes its purpose. The checkbox can also be in an indeterminate state, which is visually distinct from both checked and unchecked states. ### Options #### Sizes

Small

```html

Small

Small Checked

Small Indeterminate

```

Medium

```html

Medium

Medium Checked

Medium Indeterminate

```

Large

```html demo

Large

Large Checked

Large Indeterminate

```

Extra Large

```html demo

Extra Large

Extra Large Checked

Extra Large Indeterminate

```

#### Variants

Standard Checkboxes

Standard checkboxes are the default style for checkboxes. They are optimal for application panels where all visual elements are monochrome in order to direct focus to the content. ```html

Default

Web component

Invalid

Web component

This selection is invalid.

Disabled

Web component

```

Emphasized Checkboxes

Emphasized checkboxes are a secondary style for checkboxes. The blue color provides a visual prominence that is optimal for forms, settings, lists or grids of assets, etc. where the checkboxes need to be noticed. ```html

Default

Web component

Invalid

Web component

This selection is invalid.

Disabled

Web component

```

### States #### Invalid The `invalid` attribute indicates that the checkbox's value is invalid. When set, appropriate ARIA attributes will be automatically applied. When a checkbox is in an invalid state, provide help text to explain the error and guide the user toward a solution. Wrap the checkbox in an [``](../field-group) to associate the help text with the checkbox. (See [help text](#help-text) for more information.) **Important:** Both the `` and its child `` elements must be marked as `invalid` for the complete invalid state to display correctly: - The `invalid` attribute on `` controls help text visibility (showing the `negative-help-text` slot). - The `invalid` attribute on each `` controls the visual invalid styling on the checkbox itself. Setting only one creates a sync hazard where either the help text won't display or the checkboxes won't show invalid styling. ```html

I accept the terms and conditions

You must accept the terms to continue.

``` #### Disabled The `disabled` attribute prevents the checkbox from receiving focus or events. The checkbox will appear faded. ```html Disabled ``` #### Indeterminate The `indeterminate` attribute sets the checkbox to an indeterminate state, visually distinct from both checked and unchecked states. ```html Indeterminate ``` #### Read-only Checkboxes have a `readonly` attribute for when they’re in the disabled state but still need their labels to be shown. This allows for content to be copied, but not interacted with or changed. ```html Read-only ``` ### Help text Help text can be accessibly associated with checkboxes by using the `help-text` or `negative-help-text` slots on an `` element. When using the `negative-help-text` slot, `` will self manage the presence of this content based on the value of the `invalid` property on your `` element. Content within the `help-text` slot will be shown by default. When your `` should receive help text based on state outside of the complexity of `invalid` or not, manage the content addressed to the `help-text` from above to ensure that it displays the right messaging and possesses the right `variant`. Read more about using [help text](../help-text).

Self managed

```html

Email notifications

SMS notifications

Push notifications

Choose how you'd like to be notified.

Select at least one notification method.

```

Managed from above

```html Notification preferences

Email notifications

SMS notifications

Push notifications

Choose how you'd like to be notified.

```

Single checkbox

When a single checkbox requires validation, wrap it in an `` to associate help text: ```html

I have read and accept the terms of service

You must accept the terms of service to continue.

```

### Behaviors #### Handling events Event handlers for clicks and other user actions can be registered on an `` as they would a standard `` element. ```html Check this box to see an onclick alert. ``` ### Accessibility Checkboxes are accessible by default, rendered in HTML using the `` element. When the checkbox is set as `indeterminate` or `invalid`, the appropriate ARIA state attribute will automatically be applied. #### Include a label Every checkbox must have a label that clearly describes its purpose. The label can be provided as content within the `` element. ```html Send me text messages. ``` #### Label groups of related checkboxes Sets of checkboxes should always have a clear label that describes what the list of options represents and guides users what to do. This is important for accessibility, since a screen reader will read the label before each option. (See [field group's label documentation](../field-group/#label) for more information.) ```html

Ketchup

Mustard

Pickles

``` #### Provide help text in the correct location Checkbox groups should use help text for error messaging and descriptions. Descriptions are valuable for giving context about a selection or for clarifying the options. It is [not currently possible](https://w3c.github.io/webcomponents-cg/#cross-root-aria) to provide accessible ARIA references between elements in different shadow roots. To ensure proper association between elements, help text must be included via the `slot="help-text"` or `slot="negative-help-text"` on the parent ``. See [help text](../help-text) for more information. #### Keyboard Navigation Checkboxes can be toggled using the Space key when focused. They follow the standard tab order of the page. #### Screen readers Screen readers interpret checkboxes by announcing their role, label, current state, and role to the user. This allows users relying on assistive technology to understand and interact with the checkbox effectively. When focused, a screen reader will announce: - The label (text provided inside the or associated with it) - The state: "checked", "not checked", or "partially checked" (when indeterminate is set) - The role: "checkbox" - If the checkbox is marked as invalid, it may also announce "invalid entry" depending on the screen reader.