checkbox

A control that allows the user to toggle between checked and not checked.

By clicking this checkbox, you agree to the terms and conditions.

Installation

npx @gentleduck/cli add checkbox
npx @gentleduck/cli add checkbox

Usage

import { Checkbox } from "@/components/ui/checkbox"
import { Checkbox } from "@/components/ui/checkbox"
<Checkbox />
<Checkbox />

API

Checkbox

  • indicator?: React.ReactElement – Custom SVG or element to display as the unchecked indicator.
  • checkedIndicator?: React.ReactElement – Custom SVG or element to display when checked.
  • checked?: boolean | 'indeterminate' – Controlled checked state.
  • defaultChecked?: boolean | 'indeterminate' – Initial checked state (uncontrolled).
  • onCheckedChange?: (checked: boolean | 'indeterminate') => void – Callback when the checked state changes.
  • (plus all native input attributes except checked, onChange, and defaultChecked)

CheckboxWithLabel

  • _checkbox: CheckboxProps – Props forwarded to the internal <Checkbox />.
  • _label: React.ComponentPropsWithoutRef<typeof Label> – Props forwarded to the <Label />.
  • id?: string – Used to link the checkbox and label via htmlFor.
  • (plus all native div props)

CheckboxGroup

  • subtasks: { id: string; title: string; checked?: boolean | 'indeterminate' }[] – Array of checkbox items.
  • subtasks_default_values?: CheckboxWithLabelProps – Default props applied to all subtasks.
  • (plus all native div props)

Examples

Basic uncontrolled checkbox

Controlled checkbox

Checkbox with label

Indeterminate state

Checkbox group

Custom indicator icons

Form

Select the items you want to display in the sidebar.

API Reference

Checkbox

  • indicator (React.ReactElement, optional): Custom SVG or icon for unchecked state indicator.
  • checkedIndicator (React.ReactElement, optional): Custom SVG or icon for checked state indicator.
  • checked (boolean | 'indeterminate', optional): Controlled checked state.
  • defaultChecked (boolean | 'indeterminate', optional, default: false): Initial checked state if uncontrolled.
  • onCheckedChange ((checked: boolean | 'indeterminate') => void, optional): Callback fired when checked state changes.
  • ref (React.Ref<HTMLInputElement>, optional): Ref forwarded to the native checkbox input.
  • ...props (React.HTMLProps<HTMLInputElement>): Native <input type="checkbox"> element props.

Behavior:

  • Manages controlled and uncontrolled checked states, including 'indeterminate'.
  • Updates aria-checked and data-checked attributes to reflect current state.
  • Renders a hidden SVG indicator element (using useSvgIndicator hook).
  • Supports custom indicators for checked and unchecked states.

CheckboxWithLabel

  • id (string, required): HTML id attribute to link checkbox and label.
  • _checkbox (React.ComponentPropsWithoutRef<typeof Checkbox>, required): Props passed to the internal Checkbox component.
  • _label (React.ComponentPropsWithoutRef<typeof Label>, required): Props passed to the internal Label component.
  • ref (React.Ref<HTMLDivElement>, optional): Ref forwarded to the wrapping div.
  • ...props (React.HTMLProps<HTMLDivElement>): Native div props.

Behavior:

  • Wraps a Checkbox and a linked Label with consistent layout and spacing.
  • Ensures accessibility via matching htmlFor and id.

CheckboxGroup

  • subtasks (Array<{ id: string; title: string; checked?: boolean | 'indeterminate' }>, required): Array of subtasks to render as individual checkboxes with labels.
  • subtasks_default_values (CheckboxWithLabelProps, optional): Default props applied to each checkbox and label in the group.
  • ref (React.Ref<HTMLDivElement>, optional): Ref forwarded to the wrapping div.
  • ...props (React.HTMLProps<HTMLDivElement>): Native div props.

Behavior:

  • Renders a vertical list of CheckboxWithLabel components.
  • Applies default checkbox and label props to all items unless overridden.
  • Supports controlled checked state for each subtask.
ChartCollapsible