Checkbox Group

Shared state for a series of checkboxes. color on the group tints nested boxes that do not set their own.

Usage guidelines

• Accessible name: Form controls must have an accessible name. Label the group with aria-labelledby, wrap each box in a <label>, or use Field and Fieldset.

Anatomy

<UiCheckboxGroup>
  <UiCheckboxRoot />
</UiCheckboxGroup>

Examples

Labeling a checkbox group

Label the group with aria-labelledby and a sibling caption:

<div id="protocols-label">Allowed network protocols</div>
<UiCheckboxGroup aria-labelledby="protocols-label">
  <!-- ... -->
</UiCheckboxGroup>

An enclosing <label> is the simplest labeling pattern for each checkbox:

<label>
  <UiCheckboxRoot value="http">
    <UiCheckboxIndicator />
  </UiCheckboxRoot>
  HTTP
</label>

Rendering as a native button

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

<div id="protocols-label">Allowed network protocols</div>
<UiCheckboxGroup aria-labelledby="protocols-label">
  <UiCheckboxRoot :id="id" native-button value="http">
    <UiCheckboxIndicator />
  </UiCheckboxRoot>
  <label :for="id">HTTP</label>
</UiCheckboxGroup>

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

Form integration

Use Fieldset for the group name. Give every box the same name so checked values submit together:

<UiFieldsetRoot>
  <UiFieldsetLegend>Allowed network protocols</UiFieldsetLegend>
  <UiCheckboxGroup>
    <label>
      <UiCheckboxRoot name="allowedNetworkProtocols" value="http">
        <UiCheckboxIndicator />
      </UiCheckboxRoot>
      HTTP
    </label>
  </UiCheckboxGroup>
</UiFieldsetRoot>

Parent checkbox

A checkbox that ticks or clears the others:

1. Make the group controlled (v-model:value or :value / @update:value)
2. Pass every child value to allValues
3. Put parent on the controlling checkbox

The group sets data-indeterminate on the parent when some, but not all, children are ticked.

<UiCheckboxGroup v-model:value="selected" :all-values="apples">
  <label>
    <UiCheckboxRoot parent>
      <UiCheckboxIndicator />
    </UiCheckboxRoot>
    Apples
  </label>
  <label>
    <UiCheckboxRoot value="fuji-apple">
      <UiCheckboxIndicator />
    </UiCheckboxRoot>
    Fuji
  </label>
</UiCheckboxGroup>

Nested parent checkbox

Nest another group when a parent owns its own children. Sync the two values in the parent so ticking “Manage Users” selects every nested box.

Disabled

disabled on the group ignores presses and sets data-disabled on the group and every checkbox.

<UiCheckboxGroup disabled :default-value="['fuji-apple']">
  <UiCheckboxRoot value="fuji-apple" />
</UiCheckboxGroup>

API reference

Checkbox Group

Provides shared state to a series of checkboxes. Renders a <div role="group">.

Use Checkbox for the Root and Indicator API, including parent, value, and data-indeterminate.