> For AI agents: the complete documentation index is available at https://rickyshin93.github.io/tao-ui/llms.txt, the full documentation bundle is available at https://rickyshin93.github.io/tao-ui/llms-full.txt.

# Checkbox

Data Entry`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Selects one or more independent boolean options.

## When to use

Use Checkbox for independent choices, or CheckboxGroup when users can select multiple options from a set.

**Recommended**

- Use clear labels that describe the checked state.
- Group related options with CheckboxGroup.

**Avoid**

- Do not use CheckboxGroup when only one option may be selected; use RadioGroup instead.

## Examples


### Basic usage
```tsx preview
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function CheckboxExample() {
  const [updates, setUpdates] = useState(true);
  const [channels, setChannels] = useState(['email', 'push']);

  return (
    <Stack gap="md">
      <Checkbox
        checked={updates}
        onChange={(event) => setUpdates(event.target.checked)}
      >
        Send product updates
      </Checkbox>
      <CheckboxGroup
        value={channels}
        onChange={setChannels}
        options={[
          { label: 'Email', value: 'email' },
          { label: 'Push', value: 'push' },
          { label: 'SMS', value: 'sms', disabled: true },
        ]}
      />
    </Stack>
  );
}

export default CheckboxExample;
```

### Standalone states
```tsx preview
import { Checkbox, Stack } from '@rockshin/tao-ui';
import { useState } from 'react';

function CheckboxStates() {
  const [unchecked, setUnchecked] = useState(false);
  const [checked, setChecked] = useState(true);
  const [mixed, setMixed] = useState(false);

  return (
    <Stack direction="horizontal" gap="lg" style={{ flexWrap: 'wrap' }}>
      <Checkbox
        checked={unchecked}
        onChange={(event) => setUnchecked(event.target.checked)}
      >
        Unchecked
      </Checkbox>
      <Checkbox
        checked={checked}
        onChange={(event) => setChecked(event.target.checked)}
      >
        Checked
      </Checkbox>
      <Checkbox
        checked={mixed}
        indeterminate={!mixed}
        onChange={(event) => setMixed(event.target.checked)}
      >
        Indeterminate
      </Checkbox>
      <Checkbox disabled>Disabled</Checkbox>
      <Checkbox checked disabled onChange={() => {}}>
        Checked disabled
      </Checkbox>
    </Stack>
  );
}

export default CheckboxStates;
```

### Vertical groups
```tsx preview
import { CheckboxGroup, FormField } from '@rockshin/tao-ui';
import { useState } from 'react';

function VerticalCheckboxGroup() {
  const [value, setValue] = useState(['email']);

  return (
    <FormField label="Notifications">
      <CheckboxGroup
        direction="vertical"
        value={value}
        onChange={setValue}
        options={[
          { label: 'Email updates', value: 'email' },
          { label: 'Push notifications', value: 'push' },
          { label: 'SMS alerts', value: 'sms', disabled: true },
        ]}
      />
    </FormField>
  );
}

export default VerticalCheckboxGroup;
```

### Controlled checkbox
onChange provides a native event; read the next value from target.checked.
```tsx preview
import { useState } from 'react';
import { Checkbox, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [checked, setChecked] = useState(false);
  return (
    <Stack direction="vertical">
      <Checkbox
        checked={checked}
        onChange={(e) => setChecked(e.target.checked)}
      >
        Receive updates
      </Checkbox>
      <output>{checked ? 'Subscribed' : 'Not subscribed'}</output>
    </Stack>
  );
}
```

### Select all and indeterminate
Derive indeterminate state from the selected count instead of storing separate conflicting state.
```tsx preview
import { useState } from 'react';
import { Checkbox, CheckboxGroup, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [values, setValues] = useState<string[]>(['Read']);
  return (
    <Stack direction="vertical">
      <Checkbox
        checked={values.length === 3}
        indeterminate={values.length > 0 && values.length < 3}
        onChange={(e) =>
          setValues(e.target.checked ? ['Read', 'Write', 'Share'] : [])
        }
      >
        Select all
      </Checkbox>
      <CheckboxGroup
        options={['Read', 'Write', 'Share']}
        value={values}
        onChange={setValues}
      />
      <output>{values.join(', ') || 'None selected'}</output>
    </Stack>
  );
}
```

### Vertical options and disabled items
Object options allow individual disabled items; direction controls layout.
```tsx preview
import { CheckboxGroup } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <CheckboxGroup
      direction="vertical"
      options={[
        { label: 'Email', value: 'email' },
        { label: 'SMS', value: 'sms' },
        { label: 'Phone (unavailable)', value: 'phone', disabled: true },
      ]}
      defaultValue={['email']}
    />
  );
}
```

### Native form values
Write controlled selections into hidden inputs and read them with FormData.
```tsx preview
import { useState } from 'react';
import { CheckboxGroup, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [values, setValues] = useState<string[]>(['email']);
  const [result, setResult] = useState('');
  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        setResult(
          new FormData(e.currentTarget).getAll('channel').join(', ') || 'None',
        );
      }}
    >
      <Stack direction="vertical">
        <CheckboxGroup
          options={['email', 'sms']}
          value={values}
          onChange={setValues}
        />
        {values.map((value) => (
          <input key={value} type="hidden" name="channel" value={value} />
        ))}
        <Button type="submit">Read values</Button>
        <output>{result}</output>
      </Stack>
    </form>
  );
}
```

### Sizes and shared disabled state
A local Provider can set size or disable a group of controls.
```tsx preview
import { Checkbox, TaoProvider, Stack } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Stack direction="vertical">
      {(['small', 'medium', 'large'] as const).map((size) => (
        <TaoProvider key={size} size={size}>
          <Checkbox>{size}</Checkbox>
        </TaoProvider>
      ))}
      <TaoProvider disabled>
        <Checkbox defaultChecked>Disabled by provider</Checkbox>
      </TaoProvider>
    </Stack>
  );
}
```

## API


### [#](#checkboxgroup)CheckboxGroup



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |



### [#](#checkbox)Checkbox



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| disabled | Whether to disable | `boolean | undefined` | `-` |
| required | Require a checked value when submitting a native form. | `boolean | undefined` | `-` |

