Checkbox

Toggle a boolean value or participate in a multi-select group. Full keyboard and screen-reader support.

stable
since v0.1.0
2.01 kB
form
input

Preview

tsx

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

export default function Example() {
  return <Checkbox>Accept terms and conditions</Checkbox>;
}

Checked state

Preview

Open

tsx

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

export default function Example() {
  const [checked, setChecked] = useState(true);
  return (
    <Checkbox checked={checked} onCheckedChange={(v) => setChecked(v === true)}>
      Subscribe to newsletter
    </Checkbox>
  );
}

Indeterminate

Use checked="indeterminate" (or the shorthand indeterminate prop) for partially-selected states.

Preview

Open

tsx

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

export default function Example() {
  const [items, setItems] = useState([false, true, false]);

  const allChecked = items.every(Boolean);
  const someChecked = items.some(Boolean);
  const parentState = allChecked ? true : someChecked ? 'indeterminate' : false;

  const toggleAll = () => {
    const next = !allChecked;
    setItems(items.map(() => next));
  };

  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Checkbox checked={parentState as boolean | 'indeterminate'} onCheckedChange={toggleAll}>
        Select all
      </Checkbox>
      <div
        style={{ paddingLeft: '1.5rem', display: 'flex', flexDirection: 'column', gap: '0.5rem' }}
      >
        {['Apples', 'Bananas', 'Cherries'].map((label, i) => (
          <Checkbox
            key={label}
            checked={items[i]}
            onCheckedChange={(v) => {
              const next = [...items];
              next[i] = v === true;
              setItems(next);
            }}
          >
            {label}
          </Checkbox>
        ))}
      </div>
    </div>
  );
}

Disabled state

Preview

Open

tsx

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

export default function Example() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
      <Checkbox disabled>Disabled unchecked</Checkbox>
      <Checkbox disabled checked>
        Disabled checked
      </Checkbox>
    </div>
  );
}

Group

Use CheckboxGroup to manage a set of checkboxes as a multi-select value array.

Preview

Open

tsx

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

export default function Example() {
  const [selected, setSelected] = useState<string[]>(['react']);
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: '0.75rem' }}>
      <CheckboxGroup value={selected} onChange={setSelected} aria-label="Preferred frameworks">
        <Checkbox value="react">React</Checkbox>
        <Checkbox value="vue">Vue</Checkbox>
        <Checkbox value="svelte">Svelte</Checkbox>
        <Checkbox value="solid">Solid</Checkbox>
      </CheckboxGroup>
      <p style={{ fontSize: '0.875rem', color: 'var(--color-fg-muted, #6b7280)', margin: 0 }}>
        Selected: {selected.length > 0 ? selected.join(', ') : 'none'}
      </p>
    </div>
  );
}

API

PropTypeDefaultDescription

value

string

—

Group value — only used when this `<Checkbox>` is a child of `<CheckboxGroup>`. Mutually exclusive with `checked`/`onCheckedChange`.

checked

CheckboxState

—

Controlled checked state. `"indeterminate"` shows a dash glyph.

defaultChecked

CheckboxState

—

Uncontrolled initial checked state.

onCheckedChange

((checked: CheckboxState) => void)

—

Fires with the next checked state on user toggle.

indeterminate

boolean

—

Forces the visual indeterminate state. Equivalent to `checked="indeterminate"`.

colorScheme

"accent"|"success"|"danger"|"neutral"

"accent"

Colour palette for the checked state.

children

ReactNode

—

Optional label content — when provided, the checkbox renders inside a `<label>`.

className

string

—

aria-label

string

—

aria-labelledby

string

—

aria-describedby

string

—

disabled

boolean

—

Disables interaction and dims the control.

required

boolean

—

Marks the control as required for form submission.

invalid

boolean

—

Renders the invalid state and sets `aria-invalid`.

name

string

—

Submitted form field name.

string

—

Element id — auto-generated when omitted.

autoFocus

boolean

—

Focuses the control on mount.

size

"sm"|"md"|"lg"

"md"

Control size.

Accessibility

Exposes role="checkbox" with proper aria-checked including "mixed" for indeterminate.
Focus ring is token-driven; keyboard activation works via Space key natively.
disabled blocks both pointer and keyboard interaction.

Recipes

Use CheckboxGroup with name when submitting inside a native <form> — each checked item submits its value.
Use indeterminate on a “select all” parent checkbox to reflect partial selection.