Checkbox
An independent React adapter where Ark UI provides the parts and Zag maintains checked, mixed, focus, and form behavior.
Design
Functional preview
Running with the independent Ark UI adapter and Zag behavior.
Loading functional preview…
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.
When to choose this output
Choose this adapter in projects that adopted Ark UI and Zag as their behavioral architecture. Do not import it into the shadcn/Base UI output.
Implementation
- Status
- Beta
- Distribution
- Source adapter
Adapter source
packages/react/src/ark/checkbox.jsx
import {
Checkbox,
CheckboxContent,
CheckboxControl,
CheckboxHiddenInput,
CheckboxIndicator,
CheckboxLabel,
} from '@tis/react/ark/checkbox'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 the Ark/Zag semantics and validate Space, checked and mixed states, disabled and invalid states, visible focus, and hidden-input form submission.
Validation evidence
Covered by its independent Storybook output plus browser, responsive, keyboard, Axe, and bundle checks.