sp-checkbox

Examples API

Attributes and Properties #

Property Attribute Type Default Description
autofocus autofocus boolean false When this control is rendered, focus it automatically
checked checked boolean false
dir dir 'ltr' | 'rtl' 'ltr'
disabled disabled boolean false Disable this control. It will not receive focus or events
emphasized emphasized boolean false
indeterminate indeterminate boolean false
invalid invalid boolean false
readonly readonly boolean false
size size ElementSize
tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property

Slots #

Name Description
default slot content to display as the label for the Checkbox

CSS Custom Properties #

Name Default
--spectrum-alias-focus-ring-gap var(--spectrum-global-dimension-static-size-25)
--spectrum-checkbox-l-box-border-radius var(--spectrum-alias-border-radius-small)
--spectrum-checkbox-l-box-border-size var(--spectrum-alias-border-size-thick)
--spectrum-checkbox-l-box-size var(--spectrum-alias-control-two-size-l)
--spectrum-checkbox-l-checkmark-size var(--spectrum-alias-ui-icon-checkmark-size-200)
--spectrum-checkbox-l-height var(--spectrum-global-dimension-size-500)
--spectrum-checkbox-l-text-font-style var(--spectrum-global-font-style-regular)
--spectrum-checkbox-l-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-checkbox-l-text-gap var(--spectrum-global-dimension-size-130)
--spectrum-checkbox-l-text-line-height var(--spectrum-alias-component-text-line-height)
--spectrum-checkbox-l-text-padding-top undefined
--spectrum-checkbox-l-text-size var(--spectrum-global-dimension-font-size-200)
--spectrum-checkbox-m-box-background-color var(--spectrum-global-color-gray-75)
--spectrum-checkbox-m-box-background-color-disabled var(--spectrum-global-color-gray-75)
--spectrum-checkbox-m-box-border-color var(--spectrum-alias-toggle-border-color-default)
--spectrum-checkbox-m-box-border-color-disabled var(--spectrum-global-color-gray-400)
--spectrum-checkbox-m-box-border-color-down var(--spectrum-alias-toggle-border-color-down)
--spectrum-checkbox-m-box-border-color-error var(--spectrum-global-color-red-500)
--spectrum-checkbox-m-box-border-color-error-down var(--spectrum-global-color-red-700)
--spectrum-checkbox-m-box-border-color-error-hover var(--spectrum-global-color-red-600)
--spectrum-checkbox-m-box-border-color-hover var(--spectrum-alias-toggle-border-color-hover)
--spectrum-checkbox-m-box-border-color-key-focus var(--spectrum-alias-toggle-border-color-key-focus)
--spectrum-checkbox-m-box-border-color-selected var(--spectrum-alias-toggle-background-color-default)
--spectrum-checkbox-m-box-border-color-selected-down var(--spectrum-alias-toggle-background-color-down)
--spectrum-checkbox-m-box-border-color-selected-hover var(--spectrum-alias-toggle-background-color-hover)
--spectrum-checkbox-m-box-border-color-selected-key-focus var(--spectrum-alias-toggle-background-color-key-focus)
--spectrum-checkbox-m-box-border-radius var(--spectrum-alias-border-radius-small)
--spectrum-checkbox-m-box-border-size var(--spectrum-alias-border-size-thick)
--spectrum-checkbox-m-box-size var(--spectrum-alias-control-two-size-m)
--spectrum-checkbox-m-checkmark-color var(--spectrum-alias-toggle-icon-color-selected)
--spectrum-checkbox-m-checkmark-size var(--spectrum-alias-ui-icon-checkmark-size-100)
--spectrum-checkbox-m-emphasized-box-border-color-selected var(--spectrum-alias-toggle-background-color-emphasized-selected-default)
--spectrum-checkbox-m-emphasized-box-border-color-selected-down var(--spectrum-alias-toggle-background-color-emphasized-selected-down)
--spectrum-checkbox-m-emphasized-box-border-color-selected-hover var(--spectrum-alias-toggle-background-color-emphasized-selected-hover)
--spectrum-checkbox-m-focus-ring-color-key-focus var(--spectrum-alias-focus-ring-color)
--spectrum-checkbox-m-focus-ring-gap-key-focus var(--spectrum-alias-focus-ring-gap)
--spectrum-checkbox-m-focus-ring-size var(--spectrum-alias-focus-ring-size)
--spectrum-checkbox-m-height var(--spectrum-global-dimension-size-400)
--spectrum-checkbox-m-text-color var(--spectrum-alias-component-text-color-default)
--spectrum-checkbox-m-text-color-disabled var(--spectrum-alias-component-text-color-disabled)
--spectrum-checkbox-m-text-color-down var(--spectrum-alias-component-text-color-down)
--spectrum-checkbox-m-text-color-error var(--spectrum-alias-component-text-color-error-default)
--spectrum-checkbox-m-text-color-error-down var(--spectrum-alias-component-text-color-error-down)
--spectrum-checkbox-m-text-color-error-hover var(--spectrum-alias-component-text-color-error-hover)
--spectrum-checkbox-m-text-color-hover var(--spectrum-alias-component-text-color-hover)
--spectrum-checkbox-m-text-color-key-focus var(--spectrum-alias-component-text-color-key-focus)
--spectrum-checkbox-m-text-font-style var(--spectrum-global-font-style-regular)
--spectrum-checkbox-m-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-checkbox-m-text-gap var(--spectrum-global-dimension-size-125)
--spectrum-checkbox-m-text-line-height var(--spectrum-alias-component-text-line-height)
--spectrum-checkbox-m-text-padding-top var(--spectrum-global-dimension-size-75)
--spectrum-checkbox-m-text-size var(--spectrum-global-dimension-font-size-100)
--spectrum-checkbox-s-box-border-radius var(--spectrum-alias-border-radius-small)
--spectrum-checkbox-s-box-border-size var(--spectrum-alias-border-size-thick)
--spectrum-checkbox-s-box-size var(--spectrum-alias-control-two-size-s)
--spectrum-checkbox-s-checkmark-size var(--spectrum-alias-ui-icon-checkmark-size-75)
--spectrum-checkbox-s-height var(--spectrum-global-dimension-size-300)
--spectrum-checkbox-s-text-font-style var(--spectrum-global-font-style-regular)
--spectrum-checkbox-s-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-checkbox-s-text-gap var(--spectrum-global-dimension-size-115)
--spectrum-checkbox-s-text-line-height var(--spectrum-alias-component-text-line-height)
--spectrum-checkbox-s-text-padding-top var(--spectrum-global-dimension-static-size-50)
--spectrum-checkbox-s-text-size var(--spectrum-global-dimension-font-size-75)
--spectrum-checkbox-xl-box-border-radius var(--spectrum-alias-border-radius-small)
--spectrum-checkbox-xl-box-border-size var(--spectrum-alias-border-size-thick)
--spectrum-checkbox-xl-box-size var(--spectrum-alias-control-two-size-xl)
--spectrum-checkbox-xl-checkmark-size var(--spectrum-alias-ui-icon-checkmark-size-300)
--spectrum-checkbox-xl-height var(--spectrum-global-dimension-size-600)
--spectrum-checkbox-xl-text-font-style var(--spectrum-global-font-style-regular)
--spectrum-checkbox-xl-text-font-weight var(--spectrum-alias-body-text-font-weight)
--spectrum-checkbox-xl-text-gap var(--spectrum-global-dimension-size-160)
--spectrum-checkbox-xl-text-line-height var(--spectrum-alias-component-text-line-height)
--spectrum-checkbox-xl-text-padding-top var(--spectrum-global-dimension-size-150)
--spectrum-checkbox-xl-text-size var(--spectrum-global-dimension-font-size-300)

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 #

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

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.