sp-checkbox

NPM 1.5.0

View Storybook

Try it on webcomponents.dev
Overview API Changelog

Overview

<sp-checkbox> 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! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/checkbox

Import the side effectful registration of <sp-checkbox> via:

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:

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 Medium 
<sp-field-group horizontal label="Medium Checkboxes">
    <sp-checkbox size="m">Medium</sp-checkbox>
    <sp-checkbox size="m" checked>Medium Checked</sp-checkbox>
    <sp-checkbox size="m" indeterminate>Medium Indeterminate</sp-checkbox>
</sp-field-group>
 Large Extra Large

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.

<div style="display: flex; justify-content: space-between;">
    <div style="display: flex; flex-direction: column;">
        <h4 class="spectrum-Heading--subtitle1">Default</h4>
        <sp-checkbox>Web component</sp-checkbox>
        <sp-checkbox checked>Web component</sp-checkbox>
        <sp-checkbox indeterminate>Web component</sp-checkbox>
    </div>

    <div style="display: flex; flex-direction: column;">
        <h4 class="spectrum-Heading--subtitle1">Invalid</h4>
        <sp-checkbox invalid>Web component</sp-checkbox>
        <sp-checkbox checked invalid>Web component</sp-checkbox>
        <sp-checkbox indeterminate invalid>Web component</sp-checkbox>
    </div>

    <div style="display: flex; flex-direction: column;">
        <h4 class="spectrum-Heading--subtitle1">Disabled</h4>
        <sp-checkbox disabled>Web component</sp-checkbox>
        <sp-checkbox checked disabled>Web component</sp-checkbox>
        <sp-checkbox indeterminate disabled>Web component</sp-checkbox>
    </div>
</div>
 Emphasized Checkboxes

States

Invalid

The invalid attribute indicates that the checkbox's value is invalid. When set, appropriate ARIA attributes will be automatically applied.

<sp-checkbox invalid>Invalid</sp-checkbox>

Disabled

The disabled attribute prevents the checkbox from receiving focus or events. The checkbox will appear faded.

<sp-checkbox disabled>Disabled</sp-checkbox>

Indeterminate

The indeterminate attribute sets the checkbox to an indeterminate state, visually distinct from both checked and unchecked states.

<sp-checkbox indeterminate>Indeterminate</sp-checkbox>

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.

<sp-checkbox readonly>Read-only</sp-checkbox>

Behaviors

Handling events

Event handlers for clicks and other user actions can be registered on an <sp-checkbox> as they would a standard <input type="checkbox"> element.

<sp-checkbox
    id="checkbox-example"
    onclick="spAlert(this, '<sp-checkbox> clicked!')"
>
    Check this box to see an onclick alert.
</sp-checkbox>

Accessibility

Checkboxes are accessible by default, rendered in HTML using the <input type="checkbox"> 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 <sp-checkbox> element.

<sp-checkbox>Send me text messages.</sp-checkbox>

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 for more information.)

<sp-field-group label="Select your toppings">
    <sp-checkbox>Ketchup</sp-checkbox>
    <sp-checkbox>Mustard</sp-checkbox>
    <sp-checkbox>Pickles</sp-checkbox>
</sp-field-group>

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.