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.
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.
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.
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.
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.
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.
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,
},
]}
/>
);
}
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.
CheckboxGroupProps API
Props for managing the options and values of a checkbox group.
CheckboxOption API
Option data supplied through a checkbox group's options.