Open UI

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.

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 NameTypeDefault ValueDescription
checkedboolfalseControls whether the checkbox is checked or unchecked.
indeterminateboolfalseControls whether the checkbox has a determinable state.
defaultCheckedboolfalseThe initial value for checked. Defaults to false.
valuestring"on"The value of the checkbox.
autofocusboolfalseGet focus by default.
disabledboolfalsePrevents the user from interacting with the control. Defaults to false.
formstringnullAssociates the element with a form in the document whose id is this value.
namestring""Specify the name of the control for purposes of form submission.
requiredboolfalseIndicates that the checkbox is invalid unless checked.
readonlyboolreadonlyIndicates that the checkbox is not interactive but its value should still be submitted with the form.

Events

Event NameDetail TypeBubblesComposedCancellableDispatch Behavior
changenonetruetruefalseFired when the checkbox’s value is committed by the user.
inputnonetruetruefalseFired when the checkbox’s value changes.

Anatomy

DOM Structure

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

Slots

Slot NameDescriptionFallback Content
labelAdd custom markup for the control’s labelEmpty
indicatorContent to indicate the checkbox is in a checked or indeterminate stateElement with checked and indeterminate indicators

CSS Parts

Slot NameDescription
labelThe control’s label
indicatorIndicates the checkbox is in a checked or indeterminate state

Behavior

Accessibility

States and Interactions

State GroupStatesInitial StateDescriptionInteraction/Transition
checkedtrue/falsefalseWhen 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.
indeterminatetrue/falsefalseWhen true, displays the control with an indeterminate appearance.No interaction. Controlled programmatically.
disabledtrue/falsefalseWhen true, disables the control, preventing user interaction and displaying the control with a disabled appearance.No interaction. Controlled programmatically.
readonlytrue/falsefalseWhen 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.