Checkbox (Explainer)

Overview

The <checkbox> element is a control that allows the user to select a binary “checked” state, either checked or unchecked. The <checkbox> also supports a second binary “indeterminate” state.

The <checkbox> control is primarily leveraged to indicate a binary state. For example, many forms use a checkbox to indicate that a user has accepted terms of service or to opt in or out of email communcations.

Prior Art/Examples

Design

API

Properties

Attribute Name	Type	Default Value	Description
`checked`	`bool`	`false`	Controls whether the checkbox is checked or unchecked.
`indeterminate`	`bool`	`false`	Controls whether the checkbox has a determinable state.
`defaultChecked`	`bool`	`false`	The initial value for `checked`. Defaults to false.
`value`	`string`	`"on"`	The value of the checkbox.
`autofocus`	`bool`	`false`	Get focus by default.
`disabled`	`bool`	`false`	Prevents the user from interacting with the control. Defaults to false.
`form`	`string`	`null`	Associates the element with a form in the document whose `id` is this value.
`name`	`string`	`""`	Specify the name of the control for purposes of form submission.
`required`	`bool`	`false`	Indicates that the checkbox is invalid unless checked.
`readonly`	`bool`	`readonly`	Indicates that the checkbox is not interactive but its value should still be submitted with the form.

Events

Event Name	Detail Type	Bubbles	Composed	Cancellable	Dispatch Behavior
`change`	none	`true`	`true`	`false`	Fired when the checkbox’s `value` is committed by the user.
`input`	none	`true`	`true`	`false`	Fired when the checkbox’s `value` changes.

Anatomy

Show slots

DOM Structure

<oui-checkbox>
  <label part="label">
    <slot name="label"></slot>
  </label>
  <div part="indicator">
    <slot name="indicator"></slot>
  </div>
</oui-checkbox>

Slots

Slot Name	Description	Fallback Content
`label`	Add custom markup for the control’s label	Empty
`indicator`	Content to indicate the checkbox is in a checked or indeterminate state	Element with checked and indeterminate indicators

CSS Parts

Slot Name	Description
`label`	The control’s label
`indicator`	Indicates the checkbox is in a checked or indeterminate state

Behavior

Accessibility

States and Interactions

State Group	States	Initial State	Description	Interaction/Transition
`checked`	`true`/`false`	`false`	When `true`, associates the control with the parent form data and displays the control with a checked appearance if not also indeterminate.	User click. Controlled programmatically.
`indeterminate`	`true`/`false`	`false`	When `true`, displays the control with an indeterminate appearance.	No interaction. Controlled programmatically.
`disabled`	`true`/`false`	`false`	When `true`, disables the control, preventing user interaction and displaying the control with a disabled appearance.	No interaction. Controlled programmatically.
`readonly`	`true`/`false`	`false`	When `true`, the control’s checked value cannot be changed by user interaction.	No interaction. Controlled programmatically.

Keyboard

Keyboard users can operate the <checkbox> as follows:

<checkbox> is eligible for document focus.
<checkbox> is eligible for autofocus when the autofocus attribute is present on the host.
<checkbox> can be the target of click events (when not disabled) either through mouse click, user tap, or keyboard space key press.

Form input

Control is eligible for all native from capabilities including:

Form submission
Form validation
Form state restoration

Use with Assistive Technology

Implements the checkbox role per the HTML AAM spec.

Checkbox (Explainer)

OverviewSection titled Overview

Use CasesSection titled Use%20Cases

Prior Art/ExamplesSection titled Prior%20Art/Examples

DesignSection titled Design

APISection titled API

PropertiesSection titled Properties

EventsSection titled Events

AnatomySection titled Anatomy

DOM StructureSection titled DOM%20Structure

SlotsSection titled Slots

CSS PartsSection titled CSS%20Parts

BehaviorSection titled Behavior

AccessibilitySection titled Accessibility

States and InteractionsSection titled States%20and%20Interactions

KeyboardSection titled Keyboard

Form inputSection titled Form%20input

Use with Assistive TechnologySection titled Use%20with%20Assistive%20Technology