> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/checkbox.html

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

# Checkbox

Select one or more options, or confirm a setting.


## Basic usage

Provide the option label as content; users can toggle its checked state independently.


Receive project news

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/checkbox/basic.tsx"
import { Checkbox } from '@ifhover/leaf-ui';

export function CheckboxBasic() {
  return <Checkbox>Receive project news</Checkbox>;
}
```

Expand code

For controlled usage, pass `checked` and read the boolean from `event.target.checked` in `onChange`.


## Examples

### Checkbox group

Use `CheckboxGroup` for multiple choices. Unlike a single checkbox, its `value` and `onChange` use arrays of strings.


SubscriptionsDesign updatesProduct newsWeekly updates

group.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/checkbox/group.tsx"
import { CheckboxGroup } from '@ifhover/leaf-ui';

export function CheckboxGroupDemo() {
  return (
    <CheckboxGroup
      legend="Subscriptions"
      defaultValue={['design']}
      options={[
        { value: 'design', label: 'Design updates' },
        { value: 'product', label: 'Product news' },
        { value: 'weekly', label: 'Weekly updates' },
      ]}
    />
  );
}
```

Expand code

### Disabled states

With `disabled`, the checked state remains visible but cannot be changed by the user.


Unchecked

Receive project news

Checked

Receive project news

disabled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/checkbox/disabled.tsx"
import { Checkbox, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function CheckboxDisabled() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">Unchecked</Text>
      <Flex align="center" wrap>
        <Checkbox disabled>Receive project news</Checkbox>
      </Flex>
      <Text tone="muted">Checked</Text>
      <Flex align="center" wrap>
        <Checkbox disabled defaultChecked>
          Receive project news
        </Checkbox>
      </Flex>
    </Grid>
  );
}
```

Expand code

### Select all and indeterminate

`indeterminate` indicates a partially selected group; it does not change `checked` or the submitted value. The application maintains the child selections and select-all behavior.


Subscribe to all

Design updatesProduct newsWeekly updates

Selected 1 items

check-all.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/checkbox/check-all.tsx"
import { Checkbox, Flex, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const options = ['Design updates', 'Product news', 'Weekly updates'];

export function CheckboxCheckAll() {
  const [selected, setSelected] = useState<string[]>(['Design updates']);
  const allChecked = selected.length === options.length;
  return (
    <Flex direction="column" gap="md" align="start">
      <Checkbox
        checked={allChecked}
        indeterminate={selected.length > 0 && !allChecked}
        onChange={(event) => setSelected(event.target.checked ? [...options] : [])}
      >
        Subscribe to all
      </Checkbox>
      <Flex direction="column" gap="sm" align="start">
        {options.map((option) => (
          <Checkbox
            key={option}
            checked={selected.includes(option)}
            onChange={(event) =>
              setSelected(
                event.target.checked
                  ? [...selected, option]
                  : selected.filter((item) => item !== option),
              )
            }
          >
            {option}
          </Checkbox>
        ))}
      </Flex>
      <Text tone="muted" role="status">
        Selected {selected.length} items
      </Text>
    </Flex>
  );
}
```

Expand code

### Card choices

[](#)
Set `variant="card"` for choices with icons and descriptions.


Connected servicesMailRead and organize messagesCloud driveFind and organize filesTeam chatCurrently unavailable

surfaces.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/checkbox/surfaces.tsx"
import { CheckboxGroup } from '@ifhover/leaf-ui';
import { HardDrive, Mail, MessageSquare } from 'lucide-react';

export function CheckboxCards() {
  return (
    <CheckboxGroup
      variant="card"
      legend={'Connected services'}
      defaultValue={['mail']}
      options={[
        {
          value: 'mail',
          label: 'Mail',
          description: 'Read and organize messages',
          icon: <Mail />,
        },
        {
          value: 'drive',
          label: 'Cloud drive',
          description: 'Find and organize files',
          icon: <HardDrive />,
        },
        {
          value: 'chat',
          label: 'Team chat',
          description: 'Currently unavailable',
          icon: <MessageSquare />,
          disabled: true,
        },
      ]}
    />
  );
}
```

Expand code

### Grouped choices

Use `CheckboxGroup variant="list"` for a shared list. Keep `extra` to non-interactive content such as status tags, not buttons or links.


Mail permissionsRead messagesmail.readonlySend messagesmail.sendApprovalDelete messagesmail.modifyRestricted

list.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/checkbox/list.tsx"
import { CheckboxGroup, Tag } from '@ifhover/leaf-ui';

export function CheckboxList() {
  return (
    <CheckboxGroup
      variant="list"
      legend={'Mail permissions'}
      defaultValue={['read']}
      options={[
        { value: 'read', label: 'Read messages', description: 'mail.readonly' },
        {
          value: 'send',
          label: 'Send messages',
          description: 'mail.send',
          extra: (
            <Tag color="warning" size="sm">
              {'Approval'}
            </Tag>
          ),
        },
        {
          value: 'delete',
          label: 'Delete messages',
          description: 'mail.modify',
          extra: <Tag size="sm">{'Restricted'}</Tag>,
          disabled: true,
        },
      ]}
    />
  );
}
```

Expand code

#### Forms and reset

With `name`, only checked and enabled choices are submitted. A checkbox group submits repeated values under the same name; read them with `FormData.getAll(name)`.

Uncontrolled fields return to `defaultChecked` or `defaultValue` on form reset. For controlled fields, reset the corresponding application state as well.


## API

### Checkbox API

Native checkbox attributes such as `name`, `value`, `required` and `form` are supported. Provide `aria-label` when there is no text label. `className` and `style` apply to the label container.

| Property         | Type                                   | Default   | Description                                               |
| ---------------- | -------------------------------------- | --------- | --------------------------------------------------------- |
| `size`           | `'sm' \| 'md' \| 'lg'`                 | `'md'`    | Control size                                              |
| `variant`        | `'plain' \| 'card'`                    | `'plain'` | Plain choice or a card with a full clickable surface.     |
| `description`    | `ReactNode`                            | —         | Additional description.                                   |
| `icon`           | `ReactNode`                            | —         | Icon content.                                             |
| `extra`          | `ReactNode`                            | —         | Supplementary status or tags; avoid interactive controls. |
| `indeterminate`  | `boolean`                              | `false`   | Partially checked state                                   |
| `checked`        | `boolean`                              | —         | Controlled checked state.                                 |
| `defaultChecked` | `boolean`                              | —         | Initial checked state for uncontrolled usage.             |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>` | —         | Read the selection from event.target.checked.             |
| `disabled`       | `boolean`                              | `false`   | Disable interaction.                                      |
| `children`       | `ReactNode`                            | —         | Clickable choice label.                                   |
| `ref`            | `Ref<HTMLInputElement>`                | —         | DOM reference                                             |

### CheckboxGroupProps API

Props for managing the options and values of a checkbox group.

| Property       | Type                                                               | Default        | Description                                                            |
| -------------- | ------------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------- |
| `options`      | `readonly (`[`CheckboxOption`](#checkboxoption-api)` \| string)[]` | Required       | Available options                                                      |
| `value`        | `readonly string[]`                                                | —              | Controlled value                                                       |
| `defaultValue` | `readonly string[]`                                                | `[]`           | Initial value, restored by uncontrolled form resets                    |
| `onChange`     | `(values: string[]) => void`                                       | —              | Value change callback                                                  |
| `legend`       | `ReactNode`                                                        | —              | Field group title                                                      |
| `size`         | `'sm' \| 'md' \| 'lg'`                                             | —              | Checkbox size.                                                         |
| `variant`      | `'plain' \| 'card' \| 'list'`                                      | `'plain'`      | Plain choices, a card grid or a list with shared borders and dividers. |
| `required`     | `boolean`                                                          | —              | Require a non-empty value; compound controls validate once.            |
| `direction`    | `'horizontal' \| 'vertical'`                                       | `'horizontal'` | Layout direction of the options.                                       |

### CheckboxOption API

Option data supplied through a checkbox group's `options`.

| Property      | Type        | Default  | Description                                               |
| ------------- | ----------- | -------- | --------------------------------------------------------- |
| `value`       | `string`    | Required | Option value; unique within the group.                    |
| `label`       | `ReactNode` | Required | Display label                                             |
| `description` | `ReactNode` | —        | Additional description.                                   |
| `icon`        | `ReactNode` | —        | Icon content.                                             |
| `extra`       | `ReactNode` | —        | Supplementary status or tags; avoid interactive controls. |
| `disabled`    | `boolean`   | —        | Disable interaction.                                      |
