---
title: CheckboxGroup
description: Collect multiple choices as one array-valued field.
package: moraine
version: 0.11.0
repository: https://github.com/subframe7536/moraine
---

# CheckboxGroup

> Collect multiple choices as one array-valued field.

## Anatomy

```text
CheckboxGroup [component; slot=root; <div>]
└── fieldset [slot]
    ├── legend [slot]
    └── item [slot]
        ├── container [slot]
        │   ├── input [internal]
        │   └── control [slot]
        │       └── indicator [slot]
        │           └── icon [internal]
        └── wrapper [slot]
            ├── label [slot]
            └── description [slot]
```

The nested `<fieldset>` owns group semantics and the optional `<legend>` association.

## Usage

Use CheckboxGroup for several choices submitted as one array. Use individual
[Checkbox](https://moraine.subf.dev/components/checkbox.md) controls when the fields are independent. Use
[RadioGroup](https://moraine.subf.dev/components/radio-group.md) when only one option may be selected.

```tsx
import { CheckboxGroup } from 'moraine'

export function Example() {
  return (
    <CheckboxGroup
      aria-label="Preferences"
      items={[
        { value: 'email', label: 'Email' },
        { value: 'sms', label: 'SMS' },
      ]}
    />
  )
}
```

### Selection model

The group value is an array of item values. Pair `value` with `onValueChange` for controlled
selection, or set `defaultValue` when the group owns its initial state. `onValueChange` receives the
complete next array and fires only for user toggles. A disabled group disables all items; an item
can also be disabled independently.

`items` accepts objects with `value`, `label`, `description`, `disabled`, `indeterminate`,
`checkedIcon`, and `indeterminateIcon`. A string is shorthand for an item whose `value` and `label`
are that string. Item `value` must be unique. An item without a `value` falls back to its index.

```tsx
<CheckboxGroup
  legend="Notification preferences"
  items={options}
  value={selected()}
  onValueChange={setSelected}
/>
<CheckboxGroup legend="Toppings" items={['cheese', 'olives']} />
```

### Forms

Give the group a `name` for native form submission, or place it inside `form.Field` from
[createForm](https://moraine.subf.dev/components/form.md) for schema binding. Standalone [Field](https://moraine.subf.dev/components/field.md) supplies
labels and messages without validation. With `required`, the group is valid when at least one
enabled item is selected. Each checkbox keeps its own tab stop; the group does not use radio-style
arrow navigation.

```tsx
<CheckboxGroup name="permissions" items={roleOptions} defaultValue={['read']} />
```

### Layout and indicator

`variant` is `list` (default), `card`, or `table`. `card` draws each item as a bordered card that
toggles when clicked, and `table` joins bordered cards into one connected block. `orientation`
(`vertical` by default, or `horizontal`) sets the layout direction, and `size` accepts `sm`, `md`
(default), or `lg`.

`indicatorPosition` places the check mark at the `leading` (default) or `trailing` edge, or hides it
visually with `hidden`.

```tsx
<CheckboxGroup indicatorPosition="trailing" items={items} />
<CheckboxGroup indicatorPosition="hidden" items={items} />
```

## Examples

### Choose notification channels

Keep the group value as an array of channel ids. Pair `value` with `onValueChange` when the page
owns the selection.

```tsx
import { CheckboxGroup } from 'moraine'
import type { CheckboxGroupT } from 'moraine'
import { createSignal } from 'solid-js'

const NOTIFICATION_OPTIONS = [
  {
    label: 'Email alerts',
    value: 'email',
    description: 'Immediate notifications for critical events.',
  },
  {
    label: 'Weekly digest',
    value: 'digest',
    description: 'Summary of team activity and metric trends.',
  },
  { label: 'SMS updates', value: 'sms', description: 'Urgent security and billing alerts only.' },
] satisfies CheckboxGroupT.Item[]

export function SelectionModel() {
  const [selected, setSelected] = createSignal<string[]>(['email', 'digest'])

  return (
    <div class="flex flex-col gap-3">
      <CheckboxGroup
        legend="Notification preferences"
        items={NOTIFICATION_OPTIONS}
        value={selected()}
        onValueChange={setSelected}
      />
      <p class="text-xs text-muted-foreground">
        Selected values: <span class="text-foreground font-mono">{JSON.stringify(selected())}</span>
      </p>
    </div>
  )
}
```

### Assign locked team roles

Disable an item that must stay selected. The controlled `value` still includes that item, and the
user cannot remove it.

```tsx
import { CheckboxGroup } from 'moraine'
import type { CheckboxGroupT } from 'moraine'
import { createSignal } from 'solid-js'

export function ControlledDisabledItems() {
  const ROLES = [
    { value: 'viewer', label: 'Viewer', description: 'Read-only access to repositories' },
    { value: 'developer', label: 'Developer', description: 'Can push commits and create PRs' },
    { value: 'maintainer', label: 'Maintainer', description: 'Can merge PRs and manage releases' },
    {
      value: 'owner',
      label: 'Owner (Immutable)',
      description: 'Primary organization administrator',
      disabled: true,
    },
  ] satisfies CheckboxGroupT.Item[]

  const [value, setValue] = createSignal<string[]>(['developer', 'owner'])

  return (
    <div class="p-4 b-1 b-border rounded-xl max-w-xl space-y-4">
      <CheckboxGroup
        legend="Team member role permissions"
        variant="card"
        items={ROLES}
        value={value()}
        onValueChange={setValue}
      />
      <p class="text-xs text-muted-foreground">
        Active roles: <span class="text-foreground font-medium">{value().join(', ')}</span>
      </p>
    </div>
  )
}
```

### Require at least one permission

Bind the array to `form.Field` and reject an empty selection with a `minLength` schema rule.

```tsx
import { Button, CheckboxGroup, createForm } from 'moraine'
import type { CheckboxGroupT } from 'moraine'
import { createSignal } from 'solid-js'
import * as v from 'valibot'

const ROLE_OPTIONS = [
  { label: 'Read repository', value: 'read' },
  { label: 'Write changes', value: 'write' },
  { label: 'Admin access', value: 'admin' },
] satisfies CheckboxGroupT.Item[]

export function FormIntegration() {
  const [submitted, setSubmitted] = createSignal<string[]>([])
  const form = createForm({
    schema: v.object({
      permissions: v.pipe(
        v.array(v.string()),
        v.minLength(1, 'Select at least one permission role.'),
      ),
    }),
    initialInput: { permissions: ['read'] },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmitted(output.permissions)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="permissions"
          label="Role permissions"
          description="Assigned permissions for team members."
          required
        >
          <CheckboxGroup items={ROLE_OPTIONS} />
        </form.Field>
        <div class="flex gap-3 items-center">
          <Button type="submit" variant="soft" tone="neutral" size="sm">
            Validate
          </Button>
          <p class="text-xs text-muted-foreground">
            Active roles: {submitted().length ? submitted().join(', ') : 'read'}
          </p>
        </div>
      </div>
    </form.Form>
  )
}
```

### Put the check at the end of alert cards

`indicatorPosition="trailing"` places the check after the label on `variant="card"`. Use it when the card reads as
a row with the control on the trailing edge.

```tsx
import { CheckboxGroup } from 'moraine'
import type { CheckboxGroupT } from 'moraine'

const NOTIFICATIONS = [
  {
    value: 'mentions',
    label: 'Direct @mentions',
    description: 'When someone mentions you in a thread',
  },
  { value: 'assignee', label: 'Issue assigned', description: 'When an issue is assigned to you' },
  {
    value: 'review',
    label: 'Review requested',
    description: 'When your review is required on a PR',
  },
] satisfies CheckboxGroupT.Item[]

export function Indicator() {
  return (
    <div class="max-w-md w-full">
      <CheckboxGroup
        legend="Activity alerts"
        variant="card"
        indicatorPosition="trailing"
        items={NOTIFICATIONS}
        defaultValue={['mentions', 'review']}
      />
    </div>
  )
}
```

## API Reference

### Attributes

| Attributes | Slot | Description |
| --- | --- | --- |
| `data-disabled` | `checkbox-group`, `checkbox-group-item`, `checkbox-control`, `checkbox-indicator` | Present when the component, slot, or item is disabled. |
| `data-invalid` | `checkbox-group`, `checkbox-group-item`, `checkbox-control` | Present when the field or form has a validation error. |
| `data-readonly` | `checkbox-group`, `checkbox-group-item`, `checkbox-control` | Present when the field is in read-only mode. |
| `data-required` | `checkbox-group`, `checkbox-group-legend`, `checkbox-group-item`, `checkbox-control`, `checkbox-label` | Present when the field input is required. |
| `data-checked` | `checkbox-group-item`, `checkbox-control`, `checkbox-indicator` | Present when the item or toggle is checked. |
| `data-indeterminate` | `checkbox-group-item`, `checkbox-control`, `checkbox-indicator` | Present when the checkbox or progress state is indeterminate. |
| `data-unchecked` | `checkbox-group-item`, `checkbox-control` | Present when the checkbox, radio item, or switch is unchecked. |

### Props

Props for the CheckboxGroup component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| checkedIcon | IconT.Name \| undefined | — | Checked icon for all items; an item's own `checkedIcon` takes precedence. |
| defaultValue | string[] \| undefined | [] | Initially selected item values when uncontrolled; also the selection restored when the<br>surrounding native form is reset. |
| disabled | boolean \| undefined | false | Whether the control is disabled: it cannot be interacted with and sets `aria-disabled`.<br>When omitted, the control inherits `disabled` from the surrounding `Field`; an explicit<br>`false` overrides the `Field`. |
| id | string \| undefined | — | The ID of the control's main focusable element, which a surrounding `Field` label points to<br>with `for`. A unique ID is generated when omitted. The control's related parts (hidden<br>input, label, description) derive their IDs from it, so keep it unique on the page. |
| indeterminateIcon | IconT.Name \| undefined | — | Indeterminate icon for all items; an item's own `indeterminateIcon` takes precedence. |
| indicatorPosition | 'leading' \| 'trailing' \| 'hidden' \| undefined | — | Where the checkbox control sits relative to the label for every item (`'leading'`,<br>`'trailing'`, or `'hidden'` to visually hide the control, as in selectable cards). |
| items | (string \| {<br>  /** Value of the item, added to the group's `value` array when selected and submitted as the<br>native checkbox value. Must be unique within the group (a duplicate logs a warning in<br>development). Falls back to the item's index as a string. */<br>  value?: string;<br>  /** Label rendered beside the item's checkbox. */<br>  label?: JSX.Element;<br>  /** Description rendered under the item's label. */<br>  description?: JSX.Element;<br>  /** Whether this item is disabled. A disabled item is skipped by the group's `required`<br>validation. */<br>  disabled?: boolean;<br>  /** Displays the item in the mixed state regardless of whether its `value` is selected.<br>Toggling it still adds or removes the `value` from the group's `value` array. */<br>  indeterminate?: boolean;<br>  /** Custom checked icon for this item. Overrides the group's `checkedIcon`. */<br>  checkedIcon?: IconT.Name;<br>  /** Custom indeterminate icon for this item. Overrides the group's `indeterminateIcon`. */<br>  indeterminateIcon?: IconT.Name;<br>})[] \| undefined | — | Options to render. A string is shorthand for an item whose `value` and `label` are that<br>string. |
| legend | JSX.Element \| undefined | — | Legend that labels the group (rendered as a `<legend>` inside the `<fieldset>`). A `Field`<br>label takes precedence for `aria-labelledby`. |
| name | string \| undefined | — | The name of the control, used for native form submission. When omitted, the control uses<br>the name of its form binding or a string `name` set on the surrounding `Field`. |
| onValueChange | ((value: string[]) => void) \| undefined | — | Called after the user toggles an item, with the full new array of selected item values<br>(previous values plus or minus the toggled one, in toggle order). Not called while the group<br>is `disabled` or `readOnly`. |
| orientation | 'horizontal' \| 'vertical' \| undefined | 'vertical' | Visual layout direction. |
| readOnly | boolean \| undefined | false | Whether the control is read-only: the value is visible and focusable but cannot be changed,<br>and `aria-readonly` is set. When omitted, the control inherits `readOnly` from the<br>surrounding `Field`. |
| required | boolean \| undefined | false | Whether the control is required, which sets `aria-required` (and the native `required`<br>attribute where the control renders a native input). When omitted, the control inherits<br>`required` from the surrounding `Field`. |
| size | 'sm' \| 'md' \| 'lg' \| undefined | 'md' | Visual size of the component. |
| value | string[] \| undefined | — | The `value` of every selected item (controlled). Leave it `undefined` for uncontrolled<br>state and update it from `onValueChange`. |
| variant | 'card' \| 'table' \| 'list' \| undefined | 'list' | Visual treatment of the component. |
| class | SlotClassValue \| undefined | — | Class applied to the component root or trigger element. |
| classes | Classes \| undefined | — | Family slot class defaults for this instance. |
| style | SlotStyleValue \| undefined | — | Style applied to the component root or trigger element. |
| styles | Styles \| undefined | — | Family slot style defaults for this instance. |

**`items` example**

```tsx
import { CheckboxGroup } from 'moraine'

<CheckboxGroup
  legend="Toppings"
  defaultValue={['cheese']}
  items={[
    'cheese',
    { value: 'mushroom', label: 'Mushroom', description: 'Fresh, sliced' },
    { value: 'olives', label: 'Olives', disabled: true },
  ]}
/>
```
