Checkbox Tree

ProNew

A tree of checkboxes where a branch is checked, unchecked or partly checked from its leaves, with full keyboard support.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

When to use it

Use it to grant permissions, choose categories, pick files to include, or filter by nested facets.

Do not use it when one choice is enough (use tree-view or tree-select). Without nesting, a plain checkbox group is simpler.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/checkbox-tree

It uses tree-view, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	The tree.
`checked / defaultChecked / onCheckedChange`	`string[]`	`[]`	Ids of the checked leaves (every checked node when `cascade` is false).
`cascade`	`boolean`	`true`	A branch follows its leaves and toggles them.
`renderLabel / renderTrailing`	`(row, state) => ReactNode`	-	Customise the row. `state` is true, false or "mixed".
`...`	-	-	All `TreeView` props except selection.

Accessibility

Each row exposes aria-checked, with the value "mixed" for a partly checked branch.
The checkbox is drawn with aria-hidden markup; the row is the single focusable control, so there are no nested tab stops.
Disabled leaves keep their value and are skipped when a branch is toggled.

Keyboard

Space: check or uncheck the focused row (a branch toggles every enabled leaf below it).
All the tree keys from tree-view (arrows, Home, End, typeahead, *).

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

CheckMark is exported for rows you draw yourself.

Testing

The component ships with a Testing Library test (checkbox-tree.test.tsx) that covers its keyboard paths, roles and states.

Guide and examples

When to use it

Use it to grant permissions, choose categories, pick files to include, or filter by nested facets.

Do not use it when one choice is enough (use tree-view or tree-select). Without nesting, a plain checkbox group is simpler.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/checkbox-tree

It uses tree-view, which the CLI installs for you.

Usage

Props

Prop	Type	Default	Description
`nodes`	`TreeNode[]`	-	The tree.
`checked / defaultChecked / onCheckedChange`	`string[]`	`[]`	Ids of the checked leaves (every checked node when `cascade` is false).
`cascade`	`boolean`	`true`	A branch follows its leaves and toggles them.
`renderLabel / renderTrailing`	`(row, state) => ReactNode`	-	Customise the row. `state` is true, false or "mixed".
`...`	-	-	All `TreeView` props except selection.

Accessibility

Each row exposes aria-checked, with the value "mixed" for a partly checked branch.
The checkbox is drawn with aria-hidden markup; the row is the single focusable control, so there are no nested tab stops.
Disabled leaves keep their value and are skipped when a branch is toggled.

Keyboard

Space: check or uncheck the focused row (a branch toggles every enabled leaf below it).
All the tree keys from tree-view (arrows, Home, End, typeahead, *).

Motion respects prefers-reduced-motion: the only animation is the loading spinner, which is switched off. Layout uses logical properties, so the component works in right-to-left languages.

CheckMark is exported for rows you draw yourself.

Testing

The component ships with a Testing Library test (checkbox-tree.test.tsx) that covers its keyboard paths, roles and states.