Checkbox
A React source recipe with Base UI behavior and the public TIS Checkbox classes and tokens.
Design
Functional preview
Running with the React source recipe distributed through shadcn and based on Base UI.
Loading functional preview…
Open the React · shadcn/Base UI playground
Anatomy
1
2
3
4
1 Label (
2 Input (
3 Checkmark — CSS pseudo-element, visible when checked.
4 Indeterminate dash — CSS pseudo-element, visible when
.ds-checkbox-label) — wraps checkbox + text, extends click target.2 Input (
.ds-checkbox) — styled native <input type="checkbox">.3 Checkmark — CSS pseudo-element, visible when checked.
4 Indeterminate dash — CSS pseudo-element, visible when
indeterminate = true.
Default
Indeterminate
Sizes
Error Group
Disabled
States
| State | CSS trigger | Visual change | Token |
|---|---|---|---|
| Unchecked | --- | Neutral box fill and border | component.checkbox.box.fill.unchecked.default, component.checkbox.box.border-color.unchecked.default |
| Unchecked hover | :hover | Darker neutral box border/fill | component.checkbox.box.fill.unchecked.hover, component.checkbox.box.border-color.unchecked.hover |
| Checked | :checked | Primary box fill with checkmark | component.checkbox.box.fill.checked.default, component.checkbox.mark.fill.checked.default |
| Checked hover | :checked:hover | Darker primary box fill | component.checkbox.box.fill.checked.hover, component.checkbox.mark.fill.checked.hover |
| Indeterminate | :indeterminate | Primary box fill with indeterminate mark | component.checkbox.box.fill.indeterminate.default, component.checkbox.mark.fill.indeterminate.default |
| Focus | :focus-visible | 2px outline ring | component.checkbox.focus-ring.radius.default + component.focus-ring.* |
| Error group | .ds-checkbox-group--error | Error border on controls and message below group | component.checkbox.box.border-color.unchecked.error, semantic.feedback.error.content-default |
| Disabled | [disabled] | Muted box, mark and label | component.checkbox.box.fill.*.disabled, semantic.content.disabled |
Figma properties
| Property | Type | Default | Description |
|---|---|---|---|
Show Label | Boolean | true | Shows or hides the control label |
Label | Text | "Rótulo" | Label text (label/md) |
Show Description | Boolean | false | Shows descriptive text below the label |
Description | Text | "Texto descritivo" | Multiline description text (body/sm) |
Show Helper Text | Boolean | false | Shows helper text below the description |
Helper Text | Text | "Texto auxiliar" | Caption/sm annotation (content/secondary) |
Usage
When to use
- Zero, one, or multiple independent options may be selected.
- A binary option has a visible label and will be confirmed in a form.
When not to use
- Only one option in a group may be selected; use Radio.
- The change immediately turns a setting on or off; use Toggle.
React composition
import {
Checkbox,
CheckboxContent,
CheckboxLabel,
CheckboxTitle,
} from "@/components/ui/checkbox"
<CheckboxLabel>
<Checkbox name="summary" />
<CheckboxContent>
<CheckboxTitle>Receber resumo semanal</CheckboxTitle>
</CheckboxContent>
</CheckboxLabel>Implementation
- Status
- Beta
- Distribution
- Source via shadcn
Installation
Configure the namespace once in the React integration guide.
npx shadcn@latest add @tis/checkboxpnpm dlx shadcn@latest add @tis/checkboxyarn dlx shadcn@latest add @tis/checkboxbunx --bun shadcn@latest add @tis/checkboxPublic contract
- Registry item
@tis/checkbox- Provider
- Base UI
- Distribution
- Source copied into the application
- Status
- Beta
Accessibility
Keyboard interaction
| Key | Action |
|---|---|
Tab | Moves focus to the next checkbox |
Space | Toggles the checked state |
Accessibility
| WCAG criterion | Requirement | Status |
|---|---|---|
| 1.3.1 Info and Relationships (A) | Group related checkboxes in <fieldset> + <legend> | ✓ |
| 2.4.11 Focus Appearance (AA) | Focus ring visible via :focus-visible | ✓ |
| 2.5.8 Target Size min (AA) | Label extends click target beyond the checkbox itself | ✓ |
| 4.1.2 Name, Role, Value (A) | Native <input type="checkbox"> provides role + state automatically | ✓ |
| 3.3.1 Error Identification (A) | Group error communicated via ds-checkbox-group--error | ✓ |
Implementation notes
Uses native <input type="checkbox"> for built-in keyboard and screen reader support. The indeterminate state must be set via JavaScript (el.indeterminate = true). Always wrap related checkboxes in a <fieldset> with a <legend> to provide group context to assistive technology.
Invisible label — requires explicit ARIA
When Show Label = false and Show Description = true, link the <input> to the description via aria-labelledby="description-id". If neither is visible, use aria-label directly on the <input>. Helper Text should always be linked via aria-describedby="helper-id".
Output responsibility
Preserve Base UI semantics and test real content, focus visibility, and accessible names in the consuming application.
Validation evidence
Covered by its independent Storybook output plus browser, responsive, keyboard, Axe, and bundle checks.