Checkbox

Checkboxes allow users to select one or more items from a set of options or to toggle a single setting on or off.

Examples

Basic

Accept terms and conditions

States

Unchecked

Checked

Mixed/Indeterminate

Disabled

Disabled unchecked

Disabled checked

Custom indicator

Default indicator

Custom indicator

Controlled

Select All

Item 1

Item 2

Item 3

Overview

Checkbox provides a standard form control for binary or tri-state selections. It supports checked, unchecked, and indeterminate states, with built-in accessibility and keyboard navigation.

tsx

import { Checkbox } from "@rogo-technologies/ui/checkbox";

<div className="flex items-center gap-1">
  <Checkbox id="newsletter" />
  <label htmlFor="newsletter">Subscribe to newsletter</label>
</div>;

Usage

States

checked accepts true, false, and "mixed" (or "indeterminate").

State	Value	Use case
Unchecked	`false`	Option is not selected
Checked	`true`	Option is selected
Mixed	`"mixed"` or `"indeterminate"`	Parent checkbox when some children are selected

tsx

<Checkbox id="option" />              // uncontrolled
<Checkbox checked={false} />
<Checkbox checked={true} />
<Checkbox checked="mixed" />
<Checkbox checked="indeterminate" />  // alias

Controlled

tsx

const [isChecked, setIsChecked] = useState(false);

<Checkbox checked={isChecked} onCheckedChange={(checked) => setIsChecked(checked)} />;

Disabled

tsx

<Checkbox disabled />
<Checkbox checked disabled />

<div className="flex items-center gap-1">
  <Checkbox id="disabled" disabled />
  <label htmlFor="disabled" className="opacity-50">
    Unavailable option
  </label>
</div>

Groups with "select all"

Combine multiple checkboxes; use mixed state on the parent when some children are selected.

tsx

const [selectedItems, setSelectedItems] = useState<string[]>([]);
const allItems = ["Option 1", "Option 2", "Option 3"];

const allSelected = selectedItems.length === allItems.length;
const someSelected = selectedItems.length > 0 && !allSelected;

<Checkbox
  checked={allSelected ? true : someSelected ? "mixed" : false}
  onCheckedChange={(checked) => {
    setSelectedItems(checked ? allItems : []);
  }}
/>
<label>Select all</label>

{allItems.map((item) => (
  <Checkbox
    key={item}
    checked={selectedItems.includes(item)}
    onCheckedChange={(checked) => {
      setSelectedItems((prev) =>
        checked ? [...prev, item] : prev.filter((i) => i !== item)
      );
    }}
  />
))}

Composable API

Use CheckboxRoot and CheckboxIndicator to provide custom indicator content.

tsx

import { CheckboxRoot, CheckboxIndicator } from "@rogo-technologies/ui/checkbox";

<CheckboxRoot id="option">
  <CheckboxIndicator />
</CheckboxRoot>

<CheckboxRoot id="option">
  <CheckboxIndicator>
    <span className="text-xs">✓</span>
  </CheckboxIndicator>
</CheckboxRoot>

<CheckboxRoot id="option">
  <CheckboxIndicator>
    <IconStar className="size-3" />
  </CheckboxIndicator>
</CheckboxRoot>

With form libraries

tsx

import { useForm } from "react-hook-form";

const { register, handleSubmit } = useForm();

<form onSubmit={handleSubmit(onSubmit)}>
  <Checkbox {...register("acceptTerms")} />
  <label>Accept terms and conditions</label>
</form>;

Accessibility

Keyboard: Space toggles
Focus ring is visible
Associates with labels via id and htmlFor
Supports aria-describedby
Mixed state is announced to screen readers

tsx

<Checkbox id="option" aria-describedby="option-description" />
<label htmlFor="option">Enable notifications</label>
<p id="option-description">You'll receive email alerts for new messages.</p>

API

Checkbox

Prop	Type	Default	Description
`checked`	`boolean \| "mixed" \| "indeterminate"`	—	Controlled checked state.
`defaultChecked`	`boolean`	`false`	Initial checked state for uncontrolled usage.
`onCheckedChange`	`(checked: boolean) => void`	—	Callback when checked state changes.
`disabled`	`boolean`	`false`	Disables the checkbox.
`required`	`boolean`	`false`	Marks the checkbox as required.
`name`	`string`	—	Name attribute for form submission.
`value`	`string`	`"on"`	Value attribute for form submission.

CheckboxRoot

Prop	Type	Default	Description
`checked`	`boolean`	—	Controlled checked state.
`defaultChecked`	`boolean`	`false`	Initial checked state.
`onCheckedChange`	`(checked: boolean) => void`	—	Callback when checked state changes.
`disabled`	`boolean`	`false`	Disables the checkbox.

CheckboxIndicator

Prop	Type	Default	Description
`children`	`ReactNode`	Checkmark icon	Custom indicator content.

Guidelines

Do

Always pair checkboxes with visible labels
Use the mixed state for "select all" checkboxes when some items are selected
Group related checkboxes together visually
Use checkboxes for independent options that can all be selected
Provide clear, concise labels that describe what selecting the checkbox does

Don't

Don't use checkboxes for mutually exclusive options — use radio buttons instead
Don't use a checkbox for a single binary action — consider a switch/toggle instead
Don't disable checkboxes without explanation — provide context via tooltip or helper text
Don't use negative labels ("Don't send emails") — use positive phrasing ("Send emails")
Don't nest checkboxes more than one level deep for "select all" patterns

PreviousButton

NextCollapsible