Checkbox (Editor's Draft)

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.

Use Cases

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 commited 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
`checked-indicator`	Content to indicate the checkbox is in a checked state	Element with checked and indeterminate indcators
`indeterminate-indicator`	Content to indicate the checkbox is in an indeterminate state	Element with checked and indeterminate indcators

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.