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

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

Subscribe to all

Design updatesProduct newsWeekly updates

Selected 1 items

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

Extended features

Choose 1–2 interests

DesignDevelopmentPhotography

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

Card choices

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

Connected services

MailRead and organize messagesCloud driveFind and organize filesTeam chatCurrently unavailable

All servicesSome services are enabled

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

Grouped choices

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

Mail permissions

Read messagesmail.readonlySend messagesmail.sendNeeds approvalDelete messagesmail.modifyPolicy restriction

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

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.

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 for labels, help and errors. ConfigProvider supplies regional themes and translated built-in UI. Application labels and options are your responsibility.

Extension types

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

CheckboxGroupProps API

Property	Type	Default	Description
`options`	`readonly (CheckboxOption \| 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.

#Checkbox

#Examples

#Extended features

#Card choices

#Grouped choices

#Checkbox API

#Types

#Forms and localization

#Extension types

#CheckboxGroupProps API

#CheckboxOption API

#Surfaces and rich content