Components

Checkbox Group

Items-based multi-select built on Checkbox.

CheckboxGroup manages an array model and renders one Checkbox per option. It can include a parent select-all checkbox.

Use Checkbox Group for multiple choices from a known list.

Anatomy

#item: Replaces one item row.
#indicator: Indicator content for child checkboxes.
#parent-indicator: Indicator content for the optional select-all parent checkbox.
#[option.slot]: Per-option label override when an option has a slot key.

The group, legend, parent row, item rows, and nested checkboxes are generated by the component. Style generated parts with ui.root, ui.item, ui.parentItem, and ui.checkbox.

Usage

Notification channels

Select allToggle every enabled channel.

EmailProduct updates and changelog notes.

SMSCritical security alerts only.

PushIn-app notifications.

Selected: email

Examples

Basic group

Use the items-based API when the option list is known up front.

<script setup lang="ts">
import { ref } from "vue";

const value = ref(["email"]);
const options = [
  { value: "email", label: "Email", description: "Product and security updates." },
  { value: "sms", label: "SMS", description: "Urgent account notices." },
  { value: "push", label: "Push", description: "App notifications." },
];
</script>

<template>
  <CheckboxGroup v-model="value" legend="Notification channels" :options="options" />
</template>

Parent select-all

Use parent to give users one checkbox that controls every enabled item.

<template>
  <CheckboxGroup
    v-model="selected"
    :options="permissions"
    parent
    parent-label="All permissions"
    parent-description="Select every enabled permission."
  />
</template>

Custom label content

Set an option slot name to customize its label while keeping the built-in checkbox behavior.

<script setup lang="ts">
const plans = [
  { value: "starter", label: "Starter" },
  { value: "pro", label: "Pro", slot: "pro" },
];
</script>

<template>
  <CheckboxGroup v-model="selected" :options="plans">
    <template #pro="{ option }">
      <span class="font-medium">{{ option.label }}</span>
      <span class="ml-2 text-xs text-neutral-500">Recommended</span>
    </template>
  </CheckboxGroup>
</template>

Horizontal orientation

Use horizontal orientation for compact filters, sizes, and toolbar-like groups.

<script setup lang="ts">
const sizeOptions = [
  { value: "s", label: "S" },
  { value: "m", label: "M" },
  { value: "l", label: "L" },
  { value: "xl", label: "XL" },
];
</script>

<template>
  <CheckboxGroup
    v-model="sizes"
    :options="sizeOptions"
    orientation="horizontal"
    aria-label="Sizes"
  />
</template>

Required form group

The first enabled checkbox receives the native required constraint until at least one value is selected.

<template>
  <Form>
    <CheckboxGroup
      v-model="channels"
      name="channels"
      legend="Contact methods"
      :options="channelOptions"
      required
    />
    <Button type="submit">Save</Button>
  </Form>
</template>

Cancel a change

Use details.cancel() to block updates that violate your business rule.

<script setup lang="ts">
import type { AkazaChangeEventDetails, CheckboxGroupValue } from "akaza-ui";

function keepOne(value: CheckboxGroupValue[], details: AkazaChangeEventDetails) {
  if (value.length === 0) details.cancel();
}
</script>

<template>
  <CheckboxGroup v-model="selected" :options="options" @value-change="keepOne" />
</template>

The group uses one native validation proxy. A required empty group remains invalid when its first option is disabled or no name is set. Invalid submission focuses the first enabled checkbox. Disable the group or remove required when no option is enabled.

Field metadata and validation apply to the group. Parent select-all changes enabled values and preserves disabled selections. Native reset restores the initial selection unless canceled.

API Reference

Props

Prop	Type	Default	Description
`options`	`CheckboxGroupOption[]`	—	Options to render.
`valueKey`	`string`	—	Property used as option value.
`labelKey`	`string`	`"label"`	Property used as label.
`descriptionKey`	`string`	`"description"`	Property used as description.
`disabledKey`	`string`	`"disabled"`	Property used as disabled state.
`allValues`	`CheckboxGroupValue[]`	option values	Values controlled by the parent checkbox.
`parent`	`boolean`	`false`	Renders a select-all parent checkbox with indeterminate state.
`parentLabel`	`string`	`"Select all"`	Parent checkbox label.
`parentDescription`	`string`	—	Parent checkbox description.
`disabled`	`boolean`	`false`	Disables every item.
`required`	`boolean`	`false`	Requires at least one checked item for form submission.
`orientation`	`"horizontal" \| "vertical"`	`"vertical"`	Layout orientation data attribute.
`legend`	`string`	—	Group label used as accessible name fallback.
`name`	`string`	—	Name used by child checkbox form inputs.
`ariaLabel`	`string`	—	Accessible label when no visible legend exists.
`ariaLabelledby`	`string`	—	External accessible label id.
`ui`	`CheckboxGroupUi`	—	Classes for root, legend, item, and nested checkbox parts.

CheckboxGroupOption

Key	Type	Description
`label`	`string`	Visible option label.
`value`	`string \| number`	Submitted/model value.
`description`	`string`	Optional help text passed to the nested checkbox.
`disabled`	`boolean`	Disables this option.
`slot`	`string`	Named slot key for custom item label content.

Emits

Event	Payload	Description
`value-change`	`(value, details)`	Fired before model updates. `details.cancel()` prevents the update.

Slots

Slot	Scoped props	Description
`item`	`option`, `value`, `checked`, `disabled`	Replaces the whole item row. You own the rendered control behavior in this slot.
`indicator`	`option`, `checked`	Child checkbox indicator.
`parent-indicator`	`checked`	Parent checkbox indicator.

UI Options

Key	Description
`root`	The group wrapper.
`input`	Visually hidden native group-validation proxy.
`legend`	The visible legend element.
`parentItem`	The parent select-all item wrapper.
`item`	Each option item wrapper.
`checkbox`	Nested Checkbox UI options passed to each checkbox.

State Attributes

CheckboxGroup sets data-akaza-orientation and data-akaza-disabled on the root. Parent and item wrappers set data-akaza-state to checked, unchecked, or indeterminate, plus disabled attributes when disabled.

Styling Hooks

UI key	CSS class	Data attrs
`root`	`akaza-checkbox-group`	`data-akaza-orientation`, `data-akaza-disabled`, `data-akaza-invalid`, `data-akaza-dirty`, `data-akaza-touched`, `data-akaza-focused`, `data-akaza-filled`
`input`	`akaza-checkbox-group-input`	—
`legend`	`akaza-checkbox-group-legend`	—
`parentItem`	`akaza-checkbox-group-parent`	`data-akaza-state`, `data-akaza-disabled`
`item`	`akaza-checkbox-group-item`	`data-akaza-state`, `data-akaza-disabled`
`checkbox`	nested `Checkbox` classes	see Checkbox

Keyboard

Key	Behavior
`Tab` / `Shift + Tab`	Moves through parent and enabled child checkboxes in document order.
`Enter` / `Space`	Toggles focused checkbox. Parent control selects or clears allowed values.

Each checkbox remains in the native tab order. The group does not use roving focus.

Checkbox

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

Collapsible

A single section that can be expanded or collapsed.