ui/components/checkbox

Checkbox

Terminal-styled checkbox with [x] and bullet variants. Standalone or CheckboxGroup with built-in arrow navigation.

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Checkbox } from "@/components/ui/checkbox";5 6 export default function CheckboxDefault() {7   const [checked, setChecked] = useState(false);8   return <Checkbox checked={checked} onChange={setChecked} label="Accept terms and conditions" />;9 }10

Installation

$pnpm exec dgadd add ui/checkbox

[Installs to]src/components/ui/checkbox[Item]ui/checkbox

dgadd is not public on npm yet. Until the first release, pack @diffgazer/add from the repository and install that tarball into this app, which is what puts dgadd on pnpm exec.

UI components require Tailwind CSS v4. Local copy mode imports src/styles/styles.css; package mode uses @diffgazer/ui CSS once packages are available.

Usage

tsx

1 "use client";2 3 import { useState } from "react";4 import { Checkbox } from "@/components/ui/checkbox";5 6 export default function CheckboxDefault() {7   const [checked, setChecked] = useState(false);8   return <Checkbox checked={checked} onChange={setChecked} label="Accept terms and conditions" />;9 }10

Examples

Variants

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Checkbox } from "@/components/ui/checkbox";5 6 export default function CheckboxVariants() {7   const [indeterminateChecked, setIndeterminateChecked] = useState<boolean | "indeterminate">(8     "indeterminate",9   );10 11   return (12     <div className="flex flex-col gap-6">13       <div className="flex flex-col gap-2">14         <div className="text-xs text-muted-foreground uppercase font-bold">Indicator</div>15         <Checkbox defaultChecked label="Variant: x (default)" variant="x" />16         <Checkbox17           checked={indeterminateChecked}18           onChange={setIndeterminateChecked}19           label="Indeterminate state"20         />21         <Checkbox defaultChecked label="Variant: bullet" variant="bullet" />22       </div>23       <div className="flex flex-col gap-2">24         <div className="text-xs text-muted-foreground uppercase font-bold">Size</div>25         <Checkbox defaultChecked label="Small" size="sm" />26         <Checkbox defaultChecked label="Medium (default)" size="md" />27         <Checkbox defaultChecked label="Large" size="lg" />28       </div>29       <div className="flex flex-col gap-2">30         <div className="text-xs text-muted-foreground uppercase font-bold">Content</div>31         <Checkbox disabled label="Disabled checkbox" />32         <Checkbox33           label="With description"34           description="This checkbox has additional descriptive text below the label."35         />36       </div>37     </div>38   );39 }40

Highlight, Invalid, and Disabled

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { Checkbox, CheckboxGroup, CheckboxItem } from "@/components/ui/checkbox";5 6 export default function CheckboxStates() {7   const [highlighted, setHighlighted] = useState<string | null>("react");8 9   return (10     <div className="flex flex-col gap-6">11       <div className="flex flex-col gap-2">12         <div className="text-xs text-muted-foreground uppercase font-bold">Keyboard highlight</div>13         <CheckboxGroup14           label="Stack"15           defaultValue={["typescript"]}16           highlighted={highlighted}17           onHighlightChange={setHighlighted}18         >19           <CheckboxItem value="typescript" label="TypeScript" />20           <CheckboxItem value="react" label="React" />21           <CheckboxItem value="tailwind" label="Tailwind CSS" />22         </CheckboxGroup>23       </div>24       <div className="flex flex-col gap-2">25         <div className="text-xs text-muted-foreground uppercase font-bold">Invalid</div>26         <Checkbox aria-invalid label="Accept terms and conditions" />27       </div>28       <div className="flex flex-col gap-2">29         <div className="text-xs text-muted-foreground uppercase font-bold">Disabled group</div>30         <CheckboxGroup label="Stack" defaultValue={["typescript"]} disabled>31           <CheckboxItem value="typescript" label="TypeScript" />32           <CheckboxItem value="react" label="React" />33         </CheckboxGroup>34       </div>35     </div>36   );37 }38

Group

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { CheckboxGroup, CheckboxItem } from "@/components/ui/checkbox";5 6 export default function CheckboxGroupDemo() {7   const [value, setValue] = useState<string[]>(["typescript"]);8 9   return (10     <CheckboxGroup value={value} onChange={setValue} aria-label="Technology choices">11       <CheckboxItem value="typescript" label="TypeScript" />12       <CheckboxItem value="react" label="React" />13       <CheckboxItem value="tailwind" label="Tailwind CSS" />14       <CheckboxItem value="vite" label="Vite" />15     </CheckboxGroup>16   );17 }18

Checklist

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { CheckboxGroup, CheckboxItem } from "@/components/ui/checkbox";5 6 export default function CheckboxChecklist() {7   const [value, setValue] = useState(["setup", "tailwind"]);8 9   return (10     <CheckboxGroup value={value} onChange={setValue} aria-label="Setup checklist" strikethrough>11       <CheckboxItem value="setup" label="Set up project structure" />12       <CheckboxItem value="typescript" label="Configure TypeScript" />13       <CheckboxItem value="tailwind" label="Add Tailwind CSS" />14       <CheckboxItem value="component" label="Create first component" />15       <CheckboxItem value="tests" label="Write tests" />16     </CheckboxGroup>17   );18 }19

API Reference

Checkbox

Name	Type	Default	Description
checked	boolean \| "indeterminate"	—	Controlled checked state. Use "indeterminate" for the mixed visual state.
defaultChecked	boolean	false	Initial checked state for uncontrolled usage.
onChange	(checked: boolean) => void	—	Called when the boolean checked state changes.
value	string	"on"	Hidden native input value used for form submission.
name	string	—	Hidden native input name used for form submission.
required	boolean	false	Marks the hidden native checkbox as required.
label	ReactNode	—	Visible label associated with the custom checkbox.
description	ReactNode	—	Visible description wired with aria-describedby.
disabled	boolean	false	Disables the custom control and hidden input.
size	"sm" \| "md" \| "lg"	"md"	Selectable control size token.
variant	"x" \| "bullet"	"x"	Indicator style.
strikethrough	boolean	false	Applies muted line-through styling to the label when checked.

CheckboxGroup

Name	Type	Default	Description
value	string[]	—	Controlled selected item values.
defaultValue	string[]	[]	Initial selected values for uncontrolled usage.
onChange	(value: string[]) => void	—	Called when the selected values change.
highlighted	string \| null	—	Controlled highlighted item value for keyboard navigation.
onHighlightChange	(value: string \| null) => void	—	Called when keyboard navigation highlights a new item or clears highlight.
wrap	boolean	true	Whether arrow-key navigation wraps at the first and last item.
keyboardNavigation	boolean	true	Enable built-in arrow-key navigation.
onNavigationBoundaryReached	(direction: "previous" \| "next", event: KeyboardEvent, key: string) => void	—	Called when non-wrapping navigation reaches the first or last item. Use event/key to decide whether to hand focus to adjacent controls.
autoFocus	boolean	false	Focuses the highlighted, selected, or first enabled item when the group becomes active.
disabled	boolean	false	Disables the group and all items.
name	string	—	Shared hidden native input name for grouped form submission.
required	boolean	false	Requires at least one enabled item to be selected.
label	string	—	Visible group label rendered before the items. Also names the group unless aria-label overrides it.
aria-label	string	—	Explicit accessible name for the group. Overrides the visible label when supplied.
aria-labelledby	string	—	ID reference for an external label. Use when another element already names the group. Composed with the visible label unless aria-label is supplied.

CheckboxItem

Name	Type	Default	Description
valuerequired	string	—	Item value. Must be unique within the group.
labelrequired	ReactNode	—	Visible item label.
description	ReactNode	—	Visible item description wired with aria-describedby.
disabled	boolean	false	Disables the item.

Data attributes

Attribute	Applies to	Values	Description
data-state	Checkbox / CheckboxItem	"checked" \| "unchecked" \| "indeterminate"	Boolean visual state for styling the custom control.
data-disabled	Checkbox / CheckboxItem	present when disabled	Marks disabled controls and group items.
data-highlighted	Checkbox / CheckboxItem	present when highlighted	Marks the current keyboard-highlighted group item.
data-value	Checkbox / CheckboxItem	item value	Stable item value used by group navigation and form submission wiring.
data-diffgazer-selectable-owner	CheckboxGroup	"checkbox"	Scopes nested selectable-item discovery for keyboard navigation.

Accessibility

Keyboard Navigation

CheckboxGroup includes arrow-key navigation — with the vim aliases j/k — with wrapping and real focus movement. Control highlighted/onHighlightChange when external state coordination is needed, use autoFocus when activating a composite region, use keyboardNavigation to suspend only arrow handling, and use onNavigationBoundaryReached for composite focus handoff. Standalone Checkbox responds to Space when focused.

Key	Action
Space	Toggles a focused standalone Checkbox or CheckboxItem.
ArrowUp / k	Moves focus to the previous enabled CheckboxItem inside CheckboxGroup.
ArrowDown / j	Moves focus to the next enabled CheckboxItem inside CheckboxGroup.
Home / End	Moves focus to the first or last enabled item.
Enter	Toggles the focused/highlighted enabled group item.

Group with built-in keyboard navigation

Preview

tsx

1 "use client";2 3 import { useState } from "react";4 import { CheckboxGroup, CheckboxItem } from "@/components/ui/checkbox";5 6 export default function CheckboxGroupDemo() {7   const [value, setValue] = useState<string[]>(["typescript"]);8 9   return (10     <CheckboxGroup value={value} onChange={setValue} aria-label="Technology choices">11       <CheckboxItem value="typescript" label="TypeScript" />12       <CheckboxItem value="react" label="React" />13       <CheckboxItem value="tailwind" label="Tailwind CSS" />14       <CheckboxItem value="vite" label="Vite" />15     </CheckboxGroup>16   );17 }18

Notes

Requires @diffgazer/keys (package mode)

CheckboxGroup's arrow-key navigation imports from the required @diffgazer/keys peer. Package consumers must install @diffgazer/keys with @diffgazer/ui; packages are not yet published to npm, so until the first release install both from locally packed tarballs. Importing @diffgazer/ui/components/checkbox without keys fails at module load with an error naming the missing @diffgazer/keys package. Standalone Checkbox still needs it because the subpath bundles the group. Copy/dgadd consumers do not need the package — copy mode rewrites the keyboard hooks to local source.

Indeterminate State

Checkbox supports a third state: checked='indeterminate' renders [-] in both indicator variants. This is useful for parent checkboxes representing partially-selected groups.

Glyph Hierarchy

The brackets are chrome and render muted; the inner mark keeps the control's tone at bold weight. A checked row is therefore the only place full-contrast ink appears in the glyph column, so a long checklist can be scanned instead of read bracket by bracket. The visible text is unchanged — the indicator still reads [x], [ ], or [-] — and the whole cell stays aria-hidden.

Indicator Variants

variant='x' (default) marks the checked state with [x]; variant='bullet' marks it with [*]. Both keep the same three-character width so mixed lists stay aligned, and neither reuses Radio's [●] dot — a checkbox never reads as a radio.

Built-in Navigation

CheckboxGroup handles arrow-key navigation with real focus movement through useNavigation. Enter toggles the focused/highlighted enabled item; Space continues to work through native/item semantics. Use autoFocus to focus the highlighted, selected, or first enabled item when the group becomes active. Use highlighted, onHighlightChange, keyboardNavigation, and onNavigationBoundaryReached when coordinating highlight state across adjacent UI. Every item value must be unique within a group.

Strikethrough (Checklist Mode)

Pass strikethrough to Checkbox or CheckboxGroup to apply line-through styling and muted color to checked item labels.

Source

Install via CLI: pnpm exec dgadd add ui/checkbox. Keyboard hooks are included as standalone copies. For the full experience, use --integration keys.

Highlighted source loads after this disclosure opens. Browse the source repository.

Checkbox

Installation

Usage

Examples

Variants

Highlight, Invalid, and Disabled

Group

Checklist

API Reference

Checkbox

CheckboxGroup

CheckboxItem

Data attributes

Accessibility

Keyboard Navigation

Group with built-in keyboard navigation

Notes

Requires @diffgazer/keys (package mode)

Indeterminate State

Glyph Hierarchy

Indicator Variants

Built-in Navigation

Strikethrough (Checklist Mode)

Source

View component source (29 files)