Checkbox

A control for a boolean value. It renders a hidden native input so it can participate in forms. color sets the wash and the checked accent. There is no stroke.

Enable notifications

Usage guidelines

Accessible name: Form controls must have an accessible name. Wrap the control in a <label>, pair a sibling label with id / for, or use Field.

Anatomy

<UiCheckboxRoot>
  <UiCheckboxIndicator />
</UiCheckboxRoot>

Examples

Labeling a checkbox

An enclosing <label> is the simplest pattern:

<label>
  <UiCheckboxRoot>
    <UiCheckboxIndicator />
  </UiCheckboxRoot>
  Accept terms and conditions
</label>

Rendering as a native button

By default Root renders a <span> so it can sit inside a wrapping label. Prefer a native <button> when the label is a sibling (for / id).

Enable notifications

<label :for="id">Enable notifications</label>
<UiCheckboxRoot :id="id" native-button>
  <UiCheckboxIndicator />
</UiCheckboxRoot>

Do not wrap a native button in a <label> — that is invalid HTML.

Form integration

Use Field for the label association and form name:

Stay logged in for 7 days

<UiFieldRoot name="stayLoggedIn">
  <UiFieldLabel>
    <UiCheckboxRoot name="stayLoggedIn">
      <UiCheckboxIndicator />
    </UiCheckboxRoot>
    Stay logged in for 7 days
  </UiFieldLabel>
</UiFieldRoot>

Indeterminate

indeterminate is the mixed state: neither ticked nor unticked. A parent checkbox in a Checkbox Group sets this automatically.

Select some rows

<UiCheckboxRoot :indeterminate="mixed">
  <UiCheckboxIndicator />
</UiCheckboxRoot>

Disabled

disabled ignores presses and sets data-disabled.

Enable notifications

<UiCheckboxRoot disabled :default-checked="true">
  <UiCheckboxIndicator />
</UiCheckboxRoot>

Read-only

readOnly keeps the box visible and in the tab order, but it cannot be ticked or unticked.

Enable notifications

<UiCheckboxRoot read-only default-checked>
  <UiCheckboxIndicator />
</UiCheckboxRoot>

API reference

Root

The checkbox. Renders a <span> (or <button> when nativeButton) and a hidden <input type="checkbox"> beside it.

Prop	Type	Default	Description
`name`	`string`	—	Name for form submission.
`defaultChecked`	`boolean`	`false`	Uncontrolled initial tick.
`checked`	`boolean`	—	Controlled tick (`v-model:checked`).
`indeterminate`	`boolean`	`false`	Mixed state. Sets `data-indeterminate` and `aria-checked="mixed"`.
`value`	`string`	—	Submitted when checked. Identifies the box in a Checkbox Group. When omitted, a checked box submits `"on"`.
`form`	`string`	—	Associates the hidden input with a form id.
`nativeButton`	`boolean`	`false`	Render a `<button type="button">` instead of a span. Use with a sibling label.
`parent`	`boolean`	`false`	Controls every child in a Checkbox Group.
`uncheckedValue`	`string`	—	Submitted when unchecked. By default unchecked boxes submit nothing.
`disabled`	`boolean`	`false`	Ignore interaction.
`readOnly`	`boolean`	`false`	Visible but not togglable.
`required`	`boolean`	`false`	Required for form submission.
`id`	`string`	—	Id of the hidden input (for sibling labels).

Event	Type	Description
`@update:checked`	`(checked: boolean) => void`	Emitted when the box is ticked or unticked.

Attribute	Description
`data-checked`	Present when ticked.
`data-unchecked`	Present when not ticked.
`data-indeterminate`	Present when mixed.
`data-disabled`	Present when disabled.
`data-readonly`	Present when read-only.
`data-required`	Present when required.
`data-valid`	Present when valid (inside Field).
`data-invalid`	Present when invalid (inside Field).
`data-dirty`	Present when the value changed (inside Field).
`data-touched`	Present when blurred after focus (inside Field).
`data-filled`	Present when checked (inside Field).
`data-focused`	Present when focused.

Indicator

Shows whether the box is ticked (or mixed). Renders a <span>. Enter and leave use data-starting-style / data-ending-style.

Prop	Type	Default	Description
`keepMounted`	`boolean`	`false`	Keep the indicator in the DOM while unchecked.

Attribute	Description
`data-checked`	Present when ticked.
`data-unchecked`	Present when not ticked.
`data-indeterminate`	Present when mixed.
`data-disabled`	Present when the checkbox is disabled.
`data-readonly`	Present when the checkbox is read-only.
`data-required`	Present when the checkbox is required.
`data-valid`	Present when valid (inside Field).
`data-invalid`	Present when invalid (inside Field).
`data-dirty`	Present when the value changed (inside Field).
`data-touched`	Present when blurred after focus (inside Field).
`data-filled`	Present when checked (inside Field).
`data-focused`	Present when focused.
`data-starting-style`	Present while animating in.
`data-ending-style`	Present while animating out.