Skip to content

Checkbox

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

Checkbox renders a labeled control with checked, unchecked, and indeterminate states. It supports native forms and custom indicators.

Anatomy

  • #indicator: Visual check mark or icon inside the checkbox button.
  • #label: Label text beside the checkbox.
  • #description: Supplementary text below the label.

Usage

Email notificationsReceive updates about your account activity.Marketing emailsGet notified about new features and promotions.All updatesA mix of indeterminate, checked, and unchecked.

Examples

Custom indicator

Use #indicator to render your own checkmark or icon.

vue
@layer akaza-reset;
@import "tailwindcss";
@import "akaza-ui/dist/akaza-ui.css";

With description

Use description when the label needs supporting context.

vue
<template>
  <Avatar
    src="/avatar.jpg"
    alt="Jane Doe"
    text="JD"
    :delay-ms="300"
  />
</template>

Indeterminate state

Use "indeterminate" for parent or mixed-selection states.

vue
<Button
  :ui="{
    root: 'rounded-md bg-black px-3 py-2 text-white',
    spinner: 'size-4 animate-spin',
  }"
>
  Save
</Button>

Custom true/false values

Use custom values when the model should store domain values instead of booleans.

vue
<template>
  <Button
    as="a"
    href="/docs"
  >
    Read the docs
  </Button>
</template>

Field and native forms

Inside Field, Checkbox inherits its id, name, required/disabled state, accessible label, and error/hint description. Validation is revealed after interaction or an invalid submit, not merely because an untouched required control is empty. Invalid submission focuses the visible button. Required validation also works without a name; unnamed controls do not submit a value.

Clicking label text activates the native button, so a disabled fieldset remains disabled. Links and other interactive descendants in the label do not toggle the checkbox. Native reset restores its mount-time model unless the reset is canceled.

class/ui.wrapper style the outer wrapper. ui.root styles the checkbox button. Supply dimensions, border, radius, spacing, and disabled opacity through ui.

API Reference

Props

PropTypeDefaultDescription
disabledbooleanfalseDisables the checkbox.
idstringautoHTML id for the button element.
namestring—HTML name for form submission.
requiredbooleanfalseMarks the field as required.
trueValueunknowntrueModel value when checked.
falseValueunknownfalseModel value when unchecked.
labelstring—Label text. Slot #label takes priority.
descriptionstring—Description text. Slot #description takes priority.
ariaLabelstring—Accessible name when no visible label is rendered.
ariaDescribedbystring—IDs of external descriptive elements.
uiCheckboxUi—CSS class overrides.

Slots

SlotScoped propsDescription
indicator{ checked }Visual check mark inside the button. checked is true, false, or "indeterminate".
label—Label text. Defaults to the label prop.
description—Description text. Defaults to the description prop.

Emits

EventPayloadDescription
value-change[value: CheckboxValue, details]Fired when the checked state changes.

UI Options

KeyDescription
wrapperOuter wrapper element.
rootThe interactive button element.
indicatorThe indicator container.
inputHidden native input used for form submission.
textWrapper around label and description.
labelThe label element.
descriptionThe description element.

Styling Hooks

UI keyCSS classData attrs
wrapperakaza-checkbox-wrapper—
rootakaza-checkboxdata-akaza-state, data-akaza-disabled, data-akaza-invalid, data-akaza-dirty, data-akaza-touched, data-akaza-focused, data-akaza-filled
indicatorakaza-checkbox-indicatordata-akaza-state
inputakaza-checkbox-input—
textakaza-checkbox-text—
labelakaza-checkbox-label—
descriptionakaza-checkbox-description—

Keyboard

KeyBehavior
Enter / SpaceToggles focused checkbox.
Tab / Shift + TabUses native document focus order.

Visible label is a real <label> associated with control, so pointer and touch activation on label toggles checkbox too.

Edit this page on GitHub ↗