sp-checkbox

NPM 1.0.1

View Storybook

Try it on webcomponents.dev

Overview

API

Changelog

Description

<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

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';

Sizes

Small

<sp-field-group>
    <sp-checkbox size="s">Small</sp-checkbox>
    <sp-checkbox size="s" checked>Small Checked</sp-checkbox>
    <sp-checkbox size="s" indeterminate>Small Indeterminate</sp-checkbox>
</sp-field-group>

Medium

<sp-field-group>
    <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

<sp-field-group>
    <sp-checkbox size="l">Large</sp-checkbox>
    <sp-checkbox size="l" checked>Large Checked</sp-checkbox>
    <sp-checkbox size="l" indeterminate>Large Indeterminate</sp-checkbox>
</sp-field-group>

Extra Large

<sp-field-group>
    <sp-checkbox size="xl">Extra Large</sp-checkbox>
    <sp-checkbox size="xl" checked>Extra Large Checked</sp-checkbox>
    <sp-checkbox size="xl" indeterminate>Extra Large Indeterminate</sp-checkbox>
</sp-field-group>

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

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.

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

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

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

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-radio> clicked!')"
>
    Web component
</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.

Attributes and Properties

Property

Attribute

Type

Default

Description

checked

boolean

false

disabled

boolean

false

Disable this control. It will not receive focus or events

emphasized

boolean

false

indeterminate

boolean

false

invalid

boolean

false

name

string | undefined

readonly

boolean

false

tabIndex

tabindex

number

0

Slots

Name

Description

default slot

content to display as the label for the Checkbox

Events

Name

Type

Description

change

Event

Announces a change in the `checked` property of a Checkbox

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/checkbox

1.0.0 (2024-10-31)

Note: Version bump only for package @spectrum-web-components/checkbox

0.49.0 (2024-10-15)

Features

add static-color to replace static (#4808) (43cf086)

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/checkbox

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/checkbox

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/checkbox

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/checkbox

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/checkbox

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/checkbox

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/checkbox

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/checkbox

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/checkbox

0.42.4 (2024-05-14)

Bug Fixes

base: move lit imports to base (#4416) (b7cb07e)

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/checkbox

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/checkbox

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/checkbox

0.42.0 (2024-03-19)

Features

asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/checkbox

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/checkbox

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/checkbox

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/checkbox

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/checkbox

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/checkbox

0.40.2 (2023-12-18)

Bug Fixes

checkbox: add missing readonly prop (#3859) (35b5649)

0.40.1 (2023-12-05)

Performance Improvements

checkbox: refactor architecture for more rendering perf and DOM element count (7c2277f)

0.40.0 (2023-11-16)

Features

textfield: added name attribute to textfield (#3752) (593005a)

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/checkbox

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/checkbox

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/checkbox

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/checkbox

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/checkbox

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/checkbox

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/checkbox

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/checkbox

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/checkbox

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/checkbox

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/checkbox

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/checkbox

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/checkbox

0.30.0 (2023-05-03)

Bug Fixes

#353 with a temporary override (e6b4e37)
add support for "readonly" attribute (4bce3b7)
add t-shirt sizing to Thumbnail and support for "xxs"/"xs" sizes (520a642)
checkbox: allow events to be cancelled on checkboxbase (aab568c)
checkbox: work around specificity changes when processing Spectrum CSS and cover with tests (d53a871)
complete deprecation of "quiet" attribute in checkbox and radio (29d8452)
correct @element jsDoc listing across library (c97a632)
ensure [disabled] styling (4c067eb)
ensure aria attributes based on state (6369ff3)
ensure aria attributes based on state (6ee43de)
ensure browser understandable extensions (f4e59f7)
focusable style (48ea3e7)
implement "emphasized" styles (750bbe7)
include "type" in package.json, generate custom-elements.json (1a8d716)
include default export in the "exports" fields (f32407d)
include the "types" entry in package.json files (b432f59)
move hover/focus hoisting into conditioning (15ac2f7)
prevent tabindex=-1 elements from placing focus on their host (1ac1293)
reduce cycles (66a4efb)
shared: prevent focusable returning focus to host (745f7b0)
stop merging selectors in a way that alters the cascade (369388f)
support a wider number of sizes (ee44978)
textfield: remove use of sp-icons-* (9a5c213)
update configuration for Spectrum CSS processing for specificity (5c2e21e)
update latest Spectrum CSS beta releases (d8d3acc)
update side effect listings (8160d3a)
update to latest spectrum-css packages (a5ca19f)
use icons without "size" values (3fc7c91)
use latest @spectrum-css/* versions (c35eb86)

Features

action-button: add action button pattern (03ac00a)
action-group: add action-group pattern (d2de766)
add and use icons-ui package (d9c3ab2)
add t-shirt sizing with visual regressions to checkbox and picker elements (ce47ec8)
adopt DNA@7 base Spectrum CSS (e08cafd)
card: upgrade to Spectrum CSS v3.0.0 (84cf1a9)
checkbox: update spectrum css input (e894cb4)
conditionally load focus-visible polyfill (6b5e5cf)
field-group: add field-group pattern (f8d265c)
include all Dev Mode files in side effects (f70817c)
leverage "exports" field in package.json (321abd7)
shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)
tabs: add sp-tab-panel element (b17d276)
use :focus-visable (via polyfill) instead of :focus (11c6fc7)
use @adobe/spectrum-css@2.15.1 (3918888)
use 3.0.0-beta.* release for styles (877b485)
use latest exports specification (a7ecf4b)

Performance Improvements

use "sideEffects" listing in package.json (7271614)
use imported TypeScript helpers instead of inlining them (cc2bd0a)

Reverts

Revert "chore: release new versions" (a6d655d)

0.14.14 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.13 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.12 (2023-03-22)

Bug Fixes

move hover/focus hoisting into conditioning (15ac2f7)

0.14.11 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.10 (2023-02-23)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.9 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.8 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.7 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.6 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.5 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.4 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.3 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.2 (2022-10-17)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.1 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/checkbox

0.14.0 (2022-08-09)

Features

include all Dev Mode files in side effects (f70817c)

0.13.6 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/checkbox

0.13.5 (2022-07-18)

Bug Fixes

checkbox: allow events to be cancelled on checkboxbase (aab568c)

0.13.4 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/checkbox

0.13.3 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/checkbox

0.13.2 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/checkbox

0.13.1 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/checkbox

0.13.0 (2022-04-21)

Features

conditionally load focus-visible polyfill (6b5e5cf)

0.12.7 (2022-03-30)

Note: Version bump only for package @spectrum-web-components/checkbox

0.12.6 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.12.5 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/checkbox

0.12.4 (2022-02-22)

Note: Version bump only for package @spectrum-web-components/checkbox

0.12.3 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/checkbox

0.12.2 (2022-01-07)

Note: Version bump only for package @spectrum-web-components/checkbox

0.12.1 (2021-12-13)

Bug Fixes

add t-shirt sizing to Thumbnail and support for "xxs"/"xs" sizes (520a642)

0.12.0 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.11.1 (2021-11-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.11.0 (2021-11-02)

Features

adopt DNA@7 base Spectrum CSS (e08cafd)

0.10.9 (2021-10-12)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.8 (2021-09-20)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.7 (2021-09-13)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.6 (2021-08-24)

Bug Fixes

correct @element jsDoc listing across library (c97a632)

0.10.5 (2021-08-03)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.4 (2021-07-22)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.3 (2021-07-01)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.2 (2021-06-16)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.1 (2021-06-07)

Note: Version bump only for package @spectrum-web-components/checkbox

0.10.0 (2021-05-24)

Bug Fixes

prevent tabindex=-1 elements from placing focus on their host (1ac1293)

Features

tabs: add sp-tab-panel element (b17d276)

0.9.6 (2021-05-12)

Note: Version bump only for package @spectrum-web-components/checkbox

0.9.5 (2021-04-09)

Note: Version bump only for package @spectrum-web-components/checkbox

0.9.4 (2021-03-29)

Note: Version bump only for package @spectrum-web-components/checkbox

0.9.3 (2021-03-22)

Note: Version bump only for package @spectrum-web-components/checkbox

0.9.2 (2021-03-22)

Bug Fixes

add support for "readonly" attribute (4bce3b7)
reduce cycles (66a4efb)

0.9.1 (2021-03-05)

Note: Version bump only for package @spectrum-web-components/checkbox

0.9.0 (2021-03-04)

Bug Fixes

support a wider number of sizes (ee44978)

Features

use latest exports specification (a7ecf4b)

0.8.0 (2021-02-11)

Bug Fixes

update to latest spectrum-css packages (a5ca19f)

Features

add t-shirt sizing with visual regressions to checkbox and picker elements (ce47ec8)

0.7.2 (2021-02-02)

Note: Version bump only for package @spectrum-web-components/checkbox

0.7.1 (2021-01-28)

Note: Version bump only for package @spectrum-web-components/checkbox

0.7.0 (2021-01-21)

Bug Fixes

complete deprecation of "quiet" attribute in checkbox and radio (29d8452)
ensure [disabled] styling (4c067eb)
implement "emphasized" styles (750bbe7)
include the "types" entry in package.json files (b432f59)
stop merging selectors in a way that alters the cascade (369388f)
update configuration for Spectrum CSS processing for specificity (5c2e21e)
update latest Spectrum CSS beta releases (d8d3acc)
use icons without "size" values (3fc7c91)
use latest @spectrum-css/* versions (c35eb86)

Features

action-button: add action button pattern (03ac00a)
checkbox: update spectrum css input (e894cb4)
field-group: add field-group pattern (f8d265c)

0.6.0 (2021-01-13)

Bug Fixes

implement "emphasized" styles (750bbe7)
include the "types" entry in package.json files (b432f59)
stop merging selectors in a way that alters the cascade (369388f)
update latest Spectrum CSS beta releases (d8d3acc)
use icons without "size" values (3fc7c91)
use latest @spectrum-css/* versions (c35eb86)

Features

action-button: add action button pattern (03ac00a)
checkbox: update spectrum css input (e894cb4)
field-group: add field-group pattern (f8d265c)

0.5.4 (2020-10-12)

Note: Version bump only for package @spectrum-web-components/checkbox

0.5.3 (2020-10-12)

Bug Fixes

checkbox: work around specificity changes when processing Spectrum CSS and cover with tests (d53a871)
include default export in the "exports" fields (f32407d)

0.5.2 (2020-09-25)

Bug Fixes

update side effect listings (8160d3a)

0.5.1 (2020-09-14)

Note: Version bump only for package @spectrum-web-components/checkbox

0.5.0 (2020-08-31)

Features

action-group: add action-group pattern (d2de766)
card: upgrade to Spectrum CSS v3.0.0 (84cf1a9)
use 3.0.0-beta.* release for styles (877b485)

0.4.4 (2020-08-19)

Note: Version bump only for package @spectrum-web-components/checkbox

0.4.3 (2020-07-27)

Note: Version bump only for package @spectrum-web-components/checkbox

0.4.2 (2020-07-24)

Bug Fixes

ensure browser understandable extensions (f4e59f7)

0.4.1 (2020-07-22)

Bug Fixes

shared: prevent focusable returning focus to host (745f7b0)

0.4.0 (2020-07-17)

Features

leverage "exports" field in package.json (321abd7)

0.3.2 (2020-06-08)

Note: Version bump only for package @spectrum-web-components/checkbox

0.3.1 (2020-05-08)

Bug Fixes

ensure aria attributes based on state (6369ff3)
ensure aria attributes based on state (6ee43de)

0.3.0 (2020-04-16)

Bug Fixes

textfield: remove use of sp-icons-* (9a5c213)

Features

add and use icons-ui package (d9c3ab2)

Performance Improvements

use "sideEffects" listing in package.json (7271614)

0.2.12 (2020-04-10)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.11 (2020-04-07)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.10 (2020-03-11)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.9 (2020-02-05)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.8 (2020-02-01)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.7 (2020-01-30)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.6 (2020-01-06)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.5 (2019-12-12)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.4 (2019-12-09)

Bug Fixes

#353 with a temporary override (e6b4e37)

0.2.3 (2019-12-03)

Bug Fixes

focusable style (48ea3e7)

0.2.2 (2019-12-02)

Note: Version bump only for package @spectrum-web-components/checkbox

0.2.1 (2019-11-27)

Bug Fixes

include "type" in package.json, generate custom-elements.json (1a8d716)

0.2.0 (2019-11-19)

Features

use :focus-visable (via polyfill) instead of :focus (11c6fc7)
use @adobe/spectrum-css@2.15.1 (3918888)

0.1.5 (2019-11-01)

Note: Version bump only for package @spectrum-web-components/checkbox

0.1.4 (2019-10-14)

Performance Improvements

use imported TypeScript helpers instead of inlining them (cc2bd0a)

0.1.3 (2019-10-03)

Note: Version bump only for package @spectrum-web-components/checkbox

Spectrum Web Components

sp-checkbox

Description

Usage

Sizes

Variants

Standard checkboxes

Emphasized checkboxes

Handling events

Accessibility

API

Attributes and Properties

Slots

Events

Changelog

1.0.1 (2024-11-11)

1.0.0 (2024-10-31)

0.49.0 (2024-10-15)

Features

0.48.1 (2024-10-01)

0.48.0 (2024-09-17)

0.47.2 (2024-09-03)

0.47.1 (2024-08-27)

0.47.0 (2024-08-20)

0.46.0 (2024-08-08)

0.45.0 (2024-07-30)

0.44.0 (2024-07-15)

0.43.0 (2024-06-11)

0.42.5 (2024-05-24)

0.42.4 (2024-05-14)

Bug Fixes

0.42.3 (2024-05-01)

0.42.2 (2024-04-03)

0.42.1 (2024-04-02)

0.42.0 (2024-03-19)

Features

0.41.2 (2024-03-05)

0.41.1 (2024-02-22)

0.41.0 (2024-02-13)

0.40.5 (2024-02-05)

0.40.4 (2024-01-29)

0.40.3 (2024-01-11)

0.40.2 (2023-12-18)

Bug Fixes

0.40.1 (2023-12-05)

Performance Improvements

0.40.0 (2023-11-16)

Features

0.39.4 (2023-11-02)

0.39.3 (2023-10-18)

0.39.2 (2023-10-13)

0.39.1 (2023-10-06)

0.39.0 (2023-09-25)

0.38.0 (2023-09-05)

0.37.0 (2023-08-18)

0.36.0 (2023-08-18)

0.35.0 (2023-07-31)

0.34.0 (2023-07-11)

0.33.2 (2023-06-14)

0.33.0 (2023-06-08)

0.32.0 (2023-06-01)

0.31.0 (2023-05-17)

0.30.0 (2023-05-03)

Bug Fixes

Features

Performance Improvements

Reverts

0.14.14 (2023-04-24)

0.14.13 (2023-04-05)

0.14.12 (2023-03-22)

Bug Fixes

0.14.11 (2023-03-08)

0.14.10 (2023-02-23)

0.14.9 (2023-02-08)

0.14.8 (2023-01-23)

0.14.7 (2023-01-09)

0.14.6 (2022-12-08)

0.14.5 (2022-11-21)

0.14.4 (2022-11-14)

0.14.3 (2022-10-28)

Spectrum
Web Components