Components · Forms & selection
Checkbox
Binary selection control for multi-value boolean inputs. Split from zetta-form-v1_4.md (removed in v1.5) in v1.4.
Preview
Build with the skill
No package to install — hand this to your AI to generate or migrate the component in your stack.
Apply the Zetta "Checkbox" component to this project using the zetta-design-md skill.
WHEN TO USE
- Migrating or fixing existing code (the common case): audit the current implementation against the `checkbox` spec and CORRECT every deviation — replace off-spec values, don't only add new ones.
- New component: build it to the `checkbox` spec in this project's stack.
AUDIT & FIX (when the component already exists)
Compare it to the skill's spec and fix, don't just append: hardcoded colors/hex, off-scale radius, wrong fonts, dark/navy fills, shadows used in place of borders (or missing borders), brand lime used as a CTA or interaction (must be primary indigo), and any missing or wrong hover / focus / active / disabled / invalid state or missing 2px focus ring. Replace each with the correct Zetta token.
ALWAYS
- Pull the authoritative spec and tokens from the skill — never guess or hardcode values.
- Use this project's own component conventions and framework idioms.
- Honor the Zetta guardrails (brand = identity only, primary = interaction, shadows for overlays) and verify in Light, Dark, and Accessibility.Anatomy & rules
┌────┐
│ ✓ │ ← 20×20px checkbox (12px padding expands hit area to ~44px)
└────┘ Option label text
| State | Background | Border | Icon |
|---|---|---|---|
| Default (unchecked) | transparent |
{colors.border-strong} |
None |
| Hover | {colors.primary-bg} |
{colors.border-focus} |
None |
| Focus | transparent + 2px solid {colors.border-focus} outline |
{colors.border-strong} |
None |
| Checked | {colors.primary} |
{colors.primary} |
check white 12px |
| Indeterminate | {colors.primary} |
{colors.primary} |
remove white |
| Disabled (unchecked) | {colors.disabled-bg} |
{colors.disabled-border} |
None |
| Disabled (checked) | {colors.disabled-bg} |
{colors.disabled-border} |
check muted |
When to use
- Multiple independent options where any combination can be selected.
- Opt-in or opt-out scenarios ("Accept terms", "Subscribe to updates").
- Select-all / select-none with indeterminate state for a group.
When not to use
- Mutually exclusive options — use Radio.
- A single on/off toggle in a settings context — use Toggle Switch.
Do
- Always pair with a visible label.
- Use indeterminate state for "select all" when some but not all items are checked.
- Group related checkboxes under a
<fieldset>with<legend>.
Don't
- Don't use checkbox for actions — use a button.
- Don't rely on color alone to show checked state — the checkmark icon communicates it.
- Labels: noun or short verb phrase. "Accept terms and conditions", "Subscribe to updates".
- Sentence case. No trailing punctuation.
- Group label (legend): noun describing the group. "Notification preferences", "Permissions".
- Keep labels to one line where possible — wrap rather than truncate.
Keyboard
| Key | Behavior |
|---|---|
Tab |
Move focus to checkbox |
Space |
Toggle checked / unchecked |
Accessibility
- ARIA role: implicit
role="checkbox"on<input type="checkbox">. aria-checked="true"/"false"/"mixed"(indeterminate).aria-disabled="true"on disabled checkboxes.- Group checkboxes in
<fieldset>+<legend>for screen reader context. - Hit area: 12px padding expands the touch target toward 44×44px minimum.
- Contrast:
{colors.primary}checked fill against white: 6.06:1 (AA). Whitecheckicon on primary: 6.06:1 (AA).
Spec
Values and token references resolved straight from the Zetta spec.
checkbox
- backgroundColor
- transparent
- borderColor
- {colors.border-strong}
- borderWidth
- 2px
- borderRadius
- {rounded.sm}
- size
- 20px
- cursor
- pointer
- padding
- 12px
checkbox-hover
- borderColor
- {colors.border-focus}
checkbox-focus
- outline
- 2px solid {colors.border-focus}
- outlineOffset
- 2px
checkbox-checked
- backgroundColor
- {colors.primary}
- borderColor
- {colors.primary}
- iconColor
- {colors.primary-text}
- iconSize
- 12px
checkbox-indeterminate
- backgroundColor
- {colors.primary}
- borderColor
- {colors.primary}
- iconColor
- {colors.primary-text}
checkbox-disabled
- backgroundColor
- {colors.disabled-bg}
- borderColor
- {colors.disabled-border}
- cursor
- not-allowed