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, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/en/components/checkbox.md.

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.

basic.tsx
import { Checkbox } from '@ifhover/leaf-ui';

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

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.

Subscriptions
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' },
      ]}
    />
  );
}

Disabled states

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

Unchecked
Checked
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>
  );
}

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.

Selected 1 items
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>
  );
}

Card choices

Set variant="card" for choices with icons and descriptions.

Connected services
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,
        },
      ]}
    />
  );
}

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 permissions
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,
        },
      ]}
    />
  );
}

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.

PropertyTypeDefaultDescription
size'sm' | 'md' | 'lg''md'Control size
variant'plain' | 'card''plain'Plain choice or a card with a full clickable surface.
descriptionReactNode—Additional description.
iconReactNode—Icon content.
extraReactNode—Supplementary status or tags; avoid interactive controls.
indeterminatebooleanfalsePartially checked state
checkedboolean—Controlled checked state.
defaultCheckedboolean—Initial checked state for uncontrolled usage.
onChangeChangeEventHandler<HTMLInputElement>—Read the selection from event.target.checked.
disabledbooleanfalseDisable interaction.
childrenReactNode—Clickable choice label.
refRef<HTMLInputElement>—DOM reference

CheckboxGroupProps API

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

PropertyTypeDefaultDescription
optionsreadonly (CheckboxOption | string)[]RequiredAvailable options
valuereadonly string[]—Controlled value
defaultValuereadonly string[][]Initial value, restored by uncontrolled form resets
onChange(values: string[]) => void—Value change callback
legendReactNode—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.
requiredboolean—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.

PropertyTypeDefaultDescription
valuestringRequiredOption value; unique within the group.
labelReactNodeRequiredDisplay label
descriptionReactNode—Additional description.
iconReactNode—Icon content.
extraReactNode—Supplementary status or tags; avoid interactive controls.
disabledboolean—Disable interaction.