Checkbox

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

Accept terms and conditions.

<script setup lang="ts">
import { ACheckboxIndicator, ACheckboxRoot } from 'akar';
import { ref } from 'vue';

const checkboxOne = ref(true);
</script>

<template>
  <div class="flex flex-row items-start relative">
    <div class="flex h-5 items-center">
      <ACheckboxRoot
        v-model="checkboxOne"
        class="rounded-sm size-4 ring ring-ring-accented ring-inset overflow-hidden focus-visible:(outline-2 outline-primary outline-offset-2)"
      >
        <ACheckboxIndicator class="color-text-inverted bg-primary flex size-full items-center justify-center">
          <i
            class="i-lucide:check shrink-0 size-full"
          />
        </ACheckboxIndicator>
      </ACheckboxRoot>
    </div>

    <div class="text-sm ms-2 w-full">
      <label class="color-text font-medium block">
        Accept terms and conditions.
      </label>
    </div>
  </div>
</template>

Features

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

Anatomy

Import all parts and piece them together.

<script setup>
import { ACheckboxGroupRoot, ACheckboxIndicator, ACheckboxRoot } from 'akar';
</script>

<template>
  <ACheckboxRoot>
    <ACheckboxIndicator />
  </ACheckboxRoot>

  <!-- or with array support -->
  <ACheckboxGroupRoot>
    <ACheckboxRoot>
      <ACheckboxIndicator />
    </ACheckboxRoot>
  </ACheckboxGroupRoot>
</template>

One benefit of using Akar is its flexibility and low-level control over the components. However, this also means that you may need to manually construct more complex UI elements by combining multiple Akar components together.

If you feel there's a lot of elements that needs to be constructed manually using Akar, consider using Pohon UI instead. It provides a higher-level abstraction over Akar components with pre-defined styles and behaviors that can help you build UIs faster.

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.

Props

Prop	Default	Type
`as`	`'button'`	`APrimitiveAsTag \| Component` The element or component this component should render as. Can be overwritten 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`		`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' \| null`
`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`.

Emits

Event	Type
`update:modelValue`	`[value: boolean \| 'indeterminate']` Event handler called when the value of the checkbox changes.

Slots

Slot	Type
`modelValue`	`false \| true \| 'indeterminate'` The controlled value of the checkbox. Can be binded with v-model.
`state`	`CheckboxCheckedState` Current state

Data Attributes

Attribute	Value
`[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.

Built with Presence component - supports any animation techniques while maintaining access to presence emitted events.

Props

Prop	Default	Type
`as`	`'span'`	`APrimitiveAsTag \| Component` The element or component this component should render as. Can be overwritten 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 Attributes

Attribute	Value
`[data-state]`	`'checked' \| 'unchecked' \| 'indeterminate'`
`[data-disabled]`	Present when disabled

Group Root

Wrapper around CheckboxRoot to support array of modelValue

Props

Prop	Default	Type
`as`	`'div'`	`APrimitiveAsTag \| Component` The element or component this component should render as. Can be overwritten 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`		`AcceptableValue[]` The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
`dir`		`'ltr' \| 'rtl'` The direction of navigation between items.
`disabled`		`boolean` When `true`, prevents the user from interacting with the checkbox
`loop`		`boolean` Whether keyboard navigation should loop around
`modelValue`		`AcceptableValue[]` 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.
`orientation`		`'horizontal' \| 'vertical'` The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`rovingFocus`	`true`	`boolean` When `false`, navigating through the items using arrow keys will be disabled.

Emits

Event	Type
`update:modelValue`	`[value: AcceptableValue[]]` Event handler called when the value of the checkbox changes.

Examples

Indeterminate

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

<script setup>
import { Icon } from '@iconify/vue';
import { ACheckboxIndicator, ACheckboxRoot } from 'akar';

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

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

  <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

Key	Description
`Space`	Checks/unchecks the checkbox

Tree

A tree view component to display and interact with hierarchical data structures.

Combobox

Choose from a list of suggested values with full keyboard support.