Checkbox
updatedYou have a choice. Three, actually. A checkbox with checked, unchecked and indeterminate states.
Open Props in the corner of the example to try color, size and disabled. color takes Button's colours, primary by default, or one of your own. It fills a checked box and the circle behind it; the edge takes the colour's text shade, which keeps 3:1 against the page where a bright warning fill doesn't, and an unchecked box keeps the --input edge, so a column of empty boxes looks the same whatever their colour. An invalid checkbox still turns red. A CheckboxGroup passes its color to every checkbox in it; one with a color of its own keeps it.
size runs from xs, 14px, to xl, 24px. md, the default, is Material's 18px. The circular state layer grows with the box.
Installation
Usage
<script setup lang="ts">
import { Checkbox } from '@/components/ui/checkbox'
import { Field, FieldLabel } from '@/components/ui/field'
const accepted = ref(false)
</script>
<template>
<Field orientation="horizontal">
<Checkbox v-model="accepted" />
<FieldLabel>Accept terms and conditions</FieldLabel>
</Field>
</template>
Set name, and it submits with the form. Inside a Field, clicking the label toggles it. On its own, give it an aria-label or a Label.
When checked, the box fills with its colour, --primary by default, and the check draws itself in. Hover or press it, and a soft circle shows up behind the box.
Examples
States
v-model is true, false or 'indeterminate'. The last one is the "it's complicated" state: a "select all" checkbox when only some items are checked. Click it, and it becomes checked.
Touch target
Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.
With wrapper, the label moves along with the box.
Description
Put the label and its description in a FieldContent. The checkbox lines up with the first line of the label, and the description is added to the checkbox's aria-describedby.
A summary of new comments and mentions, once a day.
Group
CheckboxGroup collects the checked values into one array.
Wrap it in a FieldSet with a legend to name it. For a group-wide error like "pick at least one", set invalid on the fieldset, and every checkbox turns red.
Each checkbox is its own Tab stop, as everywhere else. Want one Tab stop and arrow keys instead? Turn on roving-focus.
variant and orientation lay the options out as cards, a list or a table, in a column or a row. See Choice Group.
Invalid
API Reference
class is also accepted and merged over the base classes.
Checkbox
| Prop | Default | Type and description |
|---|---|---|
| defaultValue | — | boolean | "indeterminate"The starting state when |
| modelValue | — | boolean | "indeterminate" | nullThe state, bound with |
| disabled | — | booleanDisables the checkbox. Also set by a disabled field or group. |
| value | — | AcceptableValueThe value this checkbox adds to a |
| id | — | stringOverrides the |
| trueValue | — | booleanThe value |
| falseValue | — | booleanThe value |
| name | — | stringSubmits the checkbox with its form under this name. |
| required | — | booleanMarks the checkbox required. Also set by a required field. |
| color | — | CheckboxColor | (string & {})Colour role of a checked box. Any other name picks up a colour you declare on |
| size | "md" | CheckboxSizeBox size, from 14px for |
| touchTarget | — | "none" | "expand" | "wrapper" | nullGrows the pressable area to 48px without changing how the box looks. |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: boolean | "indeterminate"]Fires when the state changes. |
CheckboxGroup
| Prop | Default | Type and description |
|---|---|---|
| defaultValue | — | AcceptableValue[]The starting array when |
| modelValue | — | AcceptableValue[]The |
| rovingFocus | false | booleanMakes the group one tab stop that arrow keys move within. Off by default, so each checkbox is a tab stop of its own, as users expect of checkboxes. |
| disabled | — | booleanDisables every checkbox in the group. |
| max | — | number | nullThe most checkboxes that can be checked at once. At the limit the unchecked ones stop toggling and get |
| as | — | AsTag | ComponentThe element or component to render. |
| asChild | — | booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it. |
| dir | — | Direction$5Reading direction for arrow keys with |
| orientation | — | Orientation$1
|
| loop | — | booleanWith |
| name | — | stringSubmits the checked values with their form under this name. |
| required | — | booleanMarks the group required. |
| variant | — | "default" | "card" | "list" | "table" | null
|
| color | "primary" | CheckboxColor | (string & {})Colour role of every checkbox in the group that has no |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: AcceptableValue[]]Fires when a checkbox in the group changes. |
| Slot | Scope and description |
|---|---|
| default | {}The checkboxes, usually each in a horizontal |
Props
- defaultValue
boolean | "indeterminate"The starting state whenv-modelis not used.- modelValue
boolean | "indeterminate" | nullThe state, bound withv-model:true,falseor'indeterminate'.- disabled
booleanDisables the checkbox. Also set by a disabled field or group.- value
AcceptableValueThe value this checkbox adds to aCheckboxGroup's array, and submits with a form.- id
stringOverrides theidtaken from a surrounding field.- trueValue
booleanThe valuev-modeltakes when checked, instead oftrue.- falseValue
booleanThe valuev-modeltakes when unchecked, instead offalse.- name
stringSubmits the checkbox with its form under this name.- required
booleanMarks the checkbox required. Also set by a required field.- color
CheckboxColor | (string & {})Colour role of a checked box. Any other name picks up a colour you declare on[data-slot][data-color="<name>"]. Without one, the checkbox takes its group'scolor, orprimary. The unchecked edge stays--input, and an invalid checkbox turnsdestructivewhatever its colour.- size
"md" CheckboxSizeBox size, from 14px forxsto 24px forxl.mdis Material's 18px.- touchTarget
"none" | "expand" | "wrapper" | nullGrows the pressable area to 48px without changing how the box looks.wrapperalso reserves that space in layout;expandmay overlap neighbours.
Emits
- update:modelValue
[value: boolean | "indeterminate"]Fires when the state changes.
Props
- defaultValue
AcceptableValue[]The starting array whenv-modelis not used.- modelValue
AcceptableValue[]Thevalues of the checked checkboxes, bound withv-model.- rovingFocus
false booleanMakes the group one tab stop that arrow keys move within. Off by default, so each checkbox is a tab stop of its own, as users expect of checkboxes.- disabled
booleanDisables every checkbox in the group.- max
number | nullThe most checkboxes that can be checked at once. At the limit the unchecked ones stop toggling and getaria-disabled, but stay focusable and keep their look, so tell users what the limit is. Needsreka-ui2.11 or later.- as
AsTag | ComponentThe element or component to render.- asChild
booleanRender the single child instead of a wrapper, merging the group's attributes and classes onto it.- dir
Direction$5Reading direction for arrow keys withrovingFocus.- orientation
Orientation$1horizontallays the options out in a row: wrapping fordefault, a grid of cards forcard, side-by-side cells forlistandtable.- loop
booleanWithrovingFocus, wraps arrow-key focus from the last checkbox to the first.- name
stringSubmits the checked values with their form under this name.- required
booleanMarks the group required.- variant
"default" | "card" | "list" | "table" | nullcard,listortablerestyle every option in the group, making each whole card or row clickable.- color
"primary" CheckboxColor | (string & {})Colour role of every checkbox in the group that has nocolorof its own, and of a selected card's edge or row's tint.
Emits
- update:modelValue
[value: AcceptableValue[]]Fires when a checkbox in the group changes.
Slots
- default
{}The checkboxes, usually each in a horizontalFieldwith its label.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| checkbox | data-state, data-color, data-size, data-disabled, data-touch-target | The checkbox. data-state is checked, unchecked or indeterminate. data-color is its own color, or the group's. |
| checkbox-group | data-variant, data-color, data-orientation | The group. |