I9kCheckboxGroup

Accessible checkbox fieldset for selecting multiple values with labels, descriptions, validation, and RTL support.

View as MarkdownView source

import { I9kCheckboxGroup } from '@9klabs/design';

Examples

Default

Choose your interests

✓EngineeringTechnical product work✓DesignProduct and interface design

<I9kCheckboxGroup
  :model-value="['engineering']"
  :options="[
    { label: 'Engineering', value: 'engineering', description: 'Technical product work' },
    { label: 'Design', value: 'design', description: 'Product and interface design' },
  ]"
  legend="Choose your interests"
/>

Horizontal

Choose your interests

✓Engineering✓Design

<I9kCheckboxGroup
  :model-value="['engineering']"
  :options="[{ label: 'Engineering', value: 'engineering' }, { label: 'Design', value: 'design' }]"
  legend="Choose your interests"
  orientation="horizontal"
/>

Validation error

Choose your interests

✓Engineering✓Design

Choose at least one interest.

<I9kCheckboxGroup
  :model-value="[]"
  :options="[{ label: 'Engineering', value: 'engineering' }, { label: 'Design', value: 'design' }]"
  legend="Choose your interests"
  error="Choose at least one interest."
  required
/>

Arabic RTL

اختر اهتماماتكيمكنك اختيار أكثر من مجال

✓هندسة البرمجيات✓تصميم المنتجات

<div dir="rtl" lang="ar">
  <I9kCheckboxGroup
    :model-value="['engineering']"
    :options="[{ label: 'هندسة البرمجيات', value: 'engineering' }, { label: 'تصميم المنتجات', value: 'design' }]"
    legend="اختر اهتماماتك"
    hint="يمكنك اختيار أكثر من مجال"
  />
</div>

Watch out

• modelValue is an array because multiple options may be selected; the emitted array is new and never mutates the prop.
• Use legend as the group label instead of adding a separate, unassociated heading.
• An option-level disabled value combines with the group-level disabled prop.

API

Props

Prop	Type	Default	Required
modelValue	readonly string[]	—	yes
options	readonly I9kCheckboxOption[]	—	yes
legend	string	—	yes
name	string	undefined	no
hint	string	undefined	no
error	string	undefined	no
required	boolean	false	no
disabled	boolean	false	no
size	'sm' | 'md' | 'lg'	'md'	no
orientation	'horizontal' | 'vertical'	'vertical'	no

Emits

Event	Payload
update:modelValue	[value: string[]]

Types

export interface I9kCheckboxOption {
  label: string;
  value: string;
  description?: string;
  disabled?: boolean;
}

Agent prompt

Paste this into an agent to have it use the component correctly. It is self-contained.

Use I9kCheckboxGroup from @9klabs/design when a user may select zero, one, or several options.

import { I9kCheckboxGroup } from '@9klabs/design';
import type { I9kCheckboxOption } from '@9klabs/design';

Props:
- modelValue: readonly string[] (required) — selected option values; use v-model in interactive forms.
- options: readonly I9kCheckboxOption[] (required) — { label, value, description?, disabled? }.
- legend: string (required) — accessible fieldset name.
- name?: string — shared native checkbox name; generated when omitted.
- hint?: string — supporting text announced with the group.
- error?: string — validation message announced as an alert.
- required?: boolean (default false) — requires at least one enabled selection.
- disabled?: boolean (default false) — disables the whole fieldset.
- size?: 'sm' | 'md' | 'lg' (default 'md').
- orientation?: 'horizontal' | 'vertical' (default 'vertical').

Emits:
- update:modelValue(value: string[]) — returns a new array after a native checkbox change.

Slots: none.

Behavior: the component renders a native fieldset and checkbox inputs. Required state clears from individual inputs after one enabled option is selected, while disabled options remain unavailable.

Usage:
<I9kCheckboxGroup
  v-model="selected"
  :options="[{ label: 'Engineering', value: 'engineering' }, { label: 'Design', value: 'design' }]"
  legend="Choose your interests"
/>