Components

Checkbox Group

Items-based multi-select built on Checkbox.

CheckboxGroup manages an array model for multiple checkbox options. It keeps Akaza's items-based API while using Checkbox for each item, including optional parent checkbox behavior.

Use it when users can choose zero, one, or many values from a known option list.

Anatomy

#item: Replaces the whole item row when you need full control.
#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>

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.
`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.

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`
`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

Checkbox

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

Collapsible

A single section that can be expanded or collapsed.