Checkbox
Binary selection control with label, description, and group layout variants.
When To Use
- Use Checkbox when the user needs to enter or choose information as part of a larger form or workflow.
- Start from this pattern when you need the interaction, spacing, and state treatment to match the rest of the system.
- Use the examples below to choose the least complex control that still communicates the user’s next step clearly.
When Not To Use
- Do not introduce a heavier or more customizable control when a simpler native-style field is sufficient.
- Do not hide required context, validation, or option meaning behind placeholder text alone.
Accessibility Notes
- Keep a visible label or an equivalent accessible name attached to the control.
- Surface validation and helper text programmatically so assistive technologies receive the same context as sighted users.
- Preserve the native focus order and keyboard interactions instead of replacing them with custom behavior.
Key Props / API
Composition surface
Checkbox keeps the native HTML or Radix API surface, then layers in design-system styling and composition defaults.
Example Code
import { Checkbox } from "@hilum/ui"
import { Label } from "@hilum/ui"
<div className="flex items-center gap-2">
<Checkbox id="mp3" defaultChecked />
<Label htmlFor="mp3">MP3 output</Label>
</div>
<div className="flex items-center gap-2">
<Checkbox id="normalize" />
<Label htmlFor="normalize">Normalize audio</Label>
</div>Checkbox · Basic
Default
Simple checkbox with label
Checkbox · List with description
Description below label
Each option has descriptive text below the label
Checkbox · List with inline description
Inline description
Description text inline with label, de-emphasized
Checkbox · Checkbox on right
Right-aligned checkboxes
Labels on left, checkboxes on right with dividers
Checkbox · Simple list with heading
Fieldset with heading
Legend above, checkboxes to the right of each label