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

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

# Checkbox

Select one or more options.

## Examples

Read event.target.checked in onChange. Use indeterminate to represent a partially selected group; it does not change the submitted value. Native name, value, required and form attributes are supported.


Receive project newsReceive weekly updatesUnavailableLocked

basic.tsx

Copy code

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

export function CheckboxBasic() {
  return (
    <Space wrap>
      <Checkbox defaultChecked>Receive project news</Checkbox>
      <Checkbox>Receive weekly updates</Checkbox>
      <Checkbox disabled>Unavailable</Checkbox>
      <Checkbox disabled defaultChecked>
        Locked
      </Checkbox>
    </Space>
  );
}
```

Expand code


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, Space, 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 (
    <Space direction="vertical" align="stretch">
      <Checkbox
        checked={allChecked}
        indeterminate={selected.length > 0 && !allChecked}
        onChange={(event) => setSelected(event.target.checked ? [...options] : [])}
      >
        Subscribe to all
      </Checkbox>
      <Flex gap="md" align="center" wrap justify="center">
        {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">Selected {selected.length} items</Text>
    </Space>
  );
}
```

Expand code

## Extended features


Choose 1–2 interestsDesignDevelopmentPhotography

extensions.tsx

Copy code

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

export function ExtensionDemo() {
  return (
    <CheckboxGroup
      legend="Choose 1–2 interests"
      options={['Design', 'Development', 'Photography']}
      defaultValue={['Design']}
      minCount={1}
      maxCount={2}
    />
  );
}
```

Expand code

## Card choices

Make the whole card clickable for choices with icons and descriptions.


Connected servicesMailRead and organize messagesCloud driveFind and organize filesTeam chatCurrently unavailableAll servicesSome services are enabled

surfaces.tsx

Copy code

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

import { HardDrive, Mail, MessageSquare } from 'lucide-react';

export function CheckboxCards() {
  
  return (
    <Space direction="vertical" align="stretch">
      <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,
          },
        ]}
      />
      <Checkbox
        variant="card"
        indeterminate
        description={'Some services are enabled'}
      >
        {'All services'}
      </Checkbox>
    </Space>
  );
}
```

Expand code

## Grouped choices

Related options share borders and row dividers, with supplementary status on the right.


Mail permissionsRead messagesmail.readonlySend messagesmail.sendNeeds approvalDelete messagesmail.modifyPolicy restriction

surfaces.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/checkbox/surfaces.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">
              {'Needs approval'}
            </Tag>
          ),
        },
        {
          value: 'delete',
          label: 'Delete messages',
          description: 'mail.modify',
          extra: <Tag size="sm">{'Policy restriction'}</Tag>,
          disabled: true,
        },
      ]}
    />
  );
}
```

Expand code

## Checkbox API

| 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 / initial checked state          |
| `defaultChecked` | `boolean`                              | —         | Controlled checked state / initial checked state          |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>` | —         | Called when the value changes.                            |
| `disabled`       | `boolean`                              | `false`   | Disable interaction.                                      |
| `children`       | `ReactNode`                            | —         | Content, or child nodes for hierarchical records.         |
| `ref`            | `Ref<HTMLInputElement>`                | —         | DOM reference                                             |

## Types

Import CheckboxProps to describe component props. Option types in the API table link to their detailed fields above.

```ts
import type { CheckboxProps } from '@ifhover/leaf-ui';
```

## Forms and localization

Use name to include values in FormData. Uncontrolled fields follow form reset; reset controlled values in application state. Place controls in [FormField](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/form.md#formfield-api) for labels, help and errors. [ConfigProvider](https://ifhover.github.io/leaf-ui/v/0.6.0/en/components/config-provider.md) supplies regional themes and translated built-in UI. Application labels and options are your responsibility.

## Extension types

```ts
import type { CheckboxGroupProps, CheckboxOption } from '@ifhover/leaf-ui';
```

## CheckboxGroupProps API

| Property       | Type                                                               | Default        | Description                                                            |
| -------------- | ------------------------------------------------------------------ | -------------- | ---------------------------------------------------------------------- |
| `options`      | `readonly (`[`CheckboxOption`](#checkboxoption-api)` \| string)[]` | Required       | 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'`                                             | —              | Size or spacing preset                                                 |
| `variant`      | `'plain' \| 'card' \| 'list'`                                      | `'plain'`      | Plain choices, a card grid or a list with shared borders and dividers. |
| `minCount`     | `number`                                                           | `0`            | Minimum selection count                                                |
| `maxCount`     | `number`                                                           | `Infinity`     | Maximum selections or visible items                                    |
| `required`     | `boolean`                                                          | —              | Require a non-empty value; compound controls validate once.            |
| `direction`    | `'horizontal' \| 'vertical'`                                       | `'horizontal'` | Layout or movement direction                                           |

## CheckboxOption API

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

## Surfaces and rich content

Checkbox variant="card" makes the whole label clickable. CheckboxGroup variant="card" arranges cards; variant="list" groups rows into one surface. description and extra provide accessible descriptions; icon is decorative. Keep extra to non-interactive status, without buttons or links. Native names, values, forms, reset and keyboard behavior remain available.