CheckboxGroup

Manages a set of Checkbox children as a single multi-select value array; works controlled or uncontrolled.

stable
since v0.1.0
1.1 kB
forms
input

Preview

tsx

import { Checkbox, CheckboxGroup, Stack } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <CheckboxGroup defaultValue={['en']} aria-label="Languages">
      <Stack gap="2">
        <Checkbox value="en">English</Checkbox>
        <Checkbox value="fr">French</Checkbox>
        <Checkbox value="de">German</Checkbox>
        <Checkbox value="es">Spanish</Checkbox>
      </Stack>
    </CheckboxGroup>
  );
}

Usage

import { Checkbox, CheckboxGroup } from "@arshad-shah/cynosure-react";

<CheckboxGroup defaultValue={["en"]} aria-label="Languages">
  <Checkbox value="en">English</Checkbox>
  <Checkbox value="fr">French</Checkbox>
</CheckboxGroup>

Each child Checkbox must carry a value — the group’s value is the array of currently-checked values.

Controlled

Drive selection from state via value + onChange. Individual checked / onCheckedChange props on the children are ignored once they’re inside a group.

Preview

Open

tsx

import { Checkbox, CheckboxGroup, Stack } from '@arshad-shah/cynosure-react';
import { useState } from 'react';

export default function Example() {
  const [value, setValue] = useState<string[]>(['en']);
  return (
    <Stack gap="3">
      <CheckboxGroup value={value} onChange={setValue} aria-label="Languages">
        <Stack gap="2">
          <Checkbox value="en">English</Checkbox>
          <Checkbox value="fr">French</Checkbox>
          <Checkbox value="de">German</Checkbox>
        </Stack>
      </CheckboxGroup>
      <p style={{ fontSize: '0.875rem' }}>
        Selected: <code>{JSON.stringify(value)}</code>
      </p>
    </Stack>
  );
}

Layout

The group renders a plain wrapper — wrap children in any layout primitive (Stack for vertical, Inline for horizontal).

Preview

Open

tsx

import { Checkbox, CheckboxGroup, Inline } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <CheckboxGroup defaultValue={['en']} aria-label="Languages">
      <Inline gap="4">
        <Checkbox value="en">English</Checkbox>
        <Checkbox value="fr">French</Checkbox>
        <Checkbox value="de">German</Checkbox>
        <Checkbox value="es">Spanish</Checkbox>
      </Inline>
    </CheckboxGroup>
  );
}

Disabled

Setting disabled on the group cascades to every child. Children can also be disabled individually.

Preview

Open

tsx

import { Checkbox, CheckboxGroup, Stack } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Stack gap="5">
      <CheckboxGroup defaultValue={['en']} disabled aria-label="Disabled group">
        <Stack gap="2">
          <Checkbox value="en">English</Checkbox>
          <Checkbox value="fr">French</Checkbox>
          <Checkbox value="de">German</Checkbox>
        </Stack>
      </CheckboxGroup>
      <CheckboxGroup defaultValue={['fr']} aria-label="Individually disabled">
        <Stack gap="2">
          <Checkbox value="en">English</Checkbox>
          <Checkbox value="fr">French</Checkbox>
          <Checkbox value="de" disabled>
            German (unavailable)
          </Checkbox>
        </Stack>
      </CheckboxGroup>
    </Stack>
  );
}

With Fieldset

For a visible legend, wrap the group in <Fieldset>.

Preview

Open

tsx

import { Checkbox, CheckboxGroup, Fieldset, Stack } from '@arshad-shah/cynosure-react';

export default function Example() {
  return (
    <Fieldset legend="Pick your languages">
      <CheckboxGroup defaultValue={['en']}>
        <Stack gap="2">
          <Checkbox value="en">English</Checkbox>
          <Checkbox value="fr">French</Checkbox>
          <Checkbox value="de">German</Checkbox>
          <Checkbox value="es">Spanish</Checkbox>
        </Stack>
      </CheckboxGroup>
    </Fieldset>
  );
}

API

PropTypeDefaultDescription

value

string[]

—

Controlled array of selected checkbox values.

defaultValue

string[]

—

Uncontrolled initial array of selected values.

onChange

((value: string[]) => void)

—

Fires with the next array on every toggle.

name

string

—

Shared submit name for every checkbox in the group. Individual `name` overrides take precedence.

disabled

boolean

—

Disables every checkbox in the group.

aria-label

string

—

A11y label for the group — resolves to `aria-label` on the wrapper.

Accessibility

Wrapper uses role="group" — pair with aria-label or a <Fieldset legend="…"> so the group has an accessible name.
Each child Checkbox keeps its native role="checkbox" and individual label, so screen-reader counting (“3 of 5”) works.
disabled on the group is propagated to every child, including their aria-disabled state.
Selection lives in a single value array — there is no separate checked to keep in sync per item.

Recipes

Pass name so each checked item submits as a repeated form value inside a native <form>.
Combine with FormField + FormMessage to drive “pick at least one” validation messaging.
Keep value items primitive strings — they round-trip cleanly through URLs and FormData.