Reka UI logoReka
backdrop
Examples
Components

Checkbox

A control that allows the user to toggle between checked and not checked.

Features

  • Supports indeterminate state.
  • Full keyboard navigation.
  • Can be controlled or uncontrolled.

Installation

Install the component from your command line.

sh
$ npm add reka-ui

Anatomy

Import all parts and piece them together.

vue
<script setup>
import { CheckboxIndicator, CheckboxRoot } from 'reka-ui'
</script>

<template>
  <CheckboxRoot>
    <CheckboxIndicator />
  </CheckboxRoot>
</template>

API Reference

Root

Contains all the parts of a checkbox. An input will also render when used within a form to ensure events propagate correctly.

PropDefaultType
as
'button'
AsTag | Component

The element or component this component should render as. Can be overwrite by asChild

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

defaultValue
false
boolean | 'indeterminate'

The value of the checkbox when it is initially rendered. Use when you do not need to control its value.

disabled
boolean

When true, prevents the user from interacting with the checkbox

id
string

Id of the element

modelValue
boolean | 'indeterminate'

The controlled value of the checkbox. Can be binded with v-model.

name
string

The name of the field. Submitted with its owning form as part of a name/value pair.

required
boolean

When true, indicates that the user must set the value before the owning form can be submitted.

value
'on'
AcceptableValue

The value given as data when submitted with a name.

EmitPayload
update:modelValue
[value: AcceptableValue]

Event handler called when the value of the checkbox changes.

Slots (default)Payload
modelValue
false | true | 'indeterminate'

Current value

state
CheckedState

Current state

Data AttributeValue
[data-state]"checked" | "unchecked" | "indeterminate"
[data-disabled]Present when disabled

Indicator

Renders when the checkbox is in a checked or indeterminate state. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.

PropDefaultType
as
'span'
AsTag | Component

The element or component this component should render as. Can be overwrite by asChild

asChild
boolean

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read our Composition guide for more details.

forceMount
boolean

Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.

Data AttributeValue
[data-state]"checked" | "unchecked" | "indeterminate"
[data-disabled]Present when disabled

Examples

Indeterminate

You can set the checkbox to indeterminate by taking control of its state.

vue
<script setup>
import { Icon } from '@iconify/vue'
import { CheckboxIndicator, CheckboxRoot } from 'reka-ui'

const checked = ref('indeterminate')
</script>

<template>
  <CheckboxRoot v-model="checked">
    <CheckboxIndicator>
      <Icon
        v-if="checked === 'indeterminate'"
        icon="radix-icons:divider-horizontal"
      />
      <Icon
        v-if="checked"
        icon="radix-icons:check"
      />
    </CheckboxIndicator>
  </CheckboxRoot>

  <button
    type="button"
    @click="() => (checked === 'indeterminate' ? (checked = false) : (checked = 'indeterminate'))"
  >
    Toggle indeterminate
  </button>
</template>

Accessibility

Adheres to the tri-state Checkbox WAI-ARIA design pattern.

Keyboard Interactions

KeyDescription
Space
Checks/unchecks the checkbox