Skip to main content

CheckboxGroup

Collect multiple choices as one array-valued field.

Notification channels

Email alerts

Weekly digests and critical updates

Push notifications

Instant alerts on mobile and desktop

SMS updates

Security and login codes

Props
Slots

Anatomy#

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 controls when the fields are independent. Use RadioGroup when only one option may be selected.

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.

<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 for schema binding. Standalone Field 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.

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

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

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.

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.

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.

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
data-disabled
Slot: checkbox-groupcheckbox-group-itemcheckbox-controlcheckbox-indicator
Description: Present when the component, slot, or item is disabled.
data-invalid
Slot: checkbox-groupcheckbox-group-itemcheckbox-control
Description: Present when the field or form has a validation error.
data-readonly
Slot: checkbox-groupcheckbox-group-itemcheckbox-control
Description: Present when the field is in read-only mode.
data-required
Slot: checkbox-groupcheckbox-group-legendcheckbox-group-itemcheckbox-controlcheckbox-label
Description: Present when the field input is required.
data-checked
Slot: checkbox-group-itemcheckbox-controlcheckbox-indicator
Description: Present when the item or toggle is checked.
data-indeterminate
Slot: checkbox-group-itemcheckbox-controlcheckbox-indicator
Description: Present when the checkbox or progress state is indeterminate.
data-unchecked
Slot: checkbox-group-itemcheckbox-control
Description: Present when the checkbox, radio item, or switch is unchecked.

Props#

Props for the CheckboxGroup component. Renders a <div> element by default.

Prop