Checkbox
Accessible checkboxes with indeterminate state, labels, validation, and form integration.
Playground
Required for signup
<Checkbox
error=""
helper="Required for signup"
label="Accept terms"
/>01 Examples
Task list
Checkboxes inside a realistic task surface — the most common pattern for to-dos, settings, and bulk-selection rows.
Completed yesterday
<div class="border-border-subtle bg-surface-elevated w-full space-y-1 rounded-2xl border p-4">
<Checkbox checked label="Design system tokens" helper="Completed yesterday" />
<Checkbox checked label="Component variants" />
<Checkbox label="Documentation pages" />
<Checkbox label="Accessibility audit" />
</div>Helper & error
Helper and error text follow the same form-field contract as Input —
error overrides helper when both are set.We send at most one email per week
You must accept the terms to continue
<Checkbox label="Newsletter" helper="We send at most one email per week" />
<Checkbox label="Terms" error="You must accept the terms to continue" intent="danger" />02 Micro-Interactions (Mint)
Mint Presets
Hover or click each checkbox to see the effect — mint targets the box, not the label.
<Checkbox mint="scale" label="Scale on hover" checked />
<Checkbox mint="glow" label="Glow on hover" checked intent="success" />
<Checkbox mint={['scale', 'glow']} label="Combined scale + glow" checked intent="danger" />03 Customization
Slot Class Overrides
Per-instance slotClasses tweak individual slots without going fully unstyled. The box exposes data-state, so overrides can target only the checked state.
<Checkbox checked label="Rounded checkbox" slotClasses={{ box: 'rounded-full' }} />
<Checkbox
checked
label="Larger box"
slotClasses={{ box: 'w-7 h-7 rounded-md', icon: 'w-5 h-5' }}
/>
<Checkbox
checked
label="Brand gradient when checked"
slotClasses={{
box: 'data-[state=checked]:border-transparent data-[state=checked]:bg-linear-to-br data-[state=checked]:from-violet-500 data-[state=checked]:to-fuchsia-500'
}}
/>Fully Custom (unstyled)
Strip all default styles with unstyled and rebuild from scratch — both instances share one slotClasses object. The box exposes data-state for conditional styling.
{@const terminal = {
control:
'inline-flex cursor-pointer items-center gap-3 font-mono text-sm text-text-primary',
box: 'flex h-5 w-5 items-center justify-center rounded border-2 border-current transition-colors data-[state=checked]:bg-text-primary data-[state=checked]:text-surface-base',
icon: 'h-3.5 w-3.5',
label: 'select-none'
}}
<Checkbox unstyled checked label="Remember me" slotClasses={terminal} />
<Checkbox unstyled label="Stay signed in" slotClasses={terminal} />The shared terminal object above is a preset in spirit
— for app-wide reuse, register it under presets.Checkbox on BlocksProvider and apply it with preset instead of importing a class map everywhere. See Customization.
04 Accessibility
Native Semantics
Built on a native <input type="checkbox"> for correct form behavior and assistive technology support. The indeterminate property automatically conveys the
mixed state, and aria-checked="mixed" is set explicitly
for maximum screen reader compatibility.
Labels & Descriptions
The label prop creates an associated <label>. Helper and error text are linked via aria-describedby, and errors set aria-invalid.
Keyboard
Tab to focus, Space to toggle. The focus ring uses focus-visible: for keyboard-only visibility and
appears on the checkbox box via the peer pattern.
Color Contrast
Error and helper messages use text alongside color to convey state. The checkbox icon (check / minus) meets WCAG AA contrast against all intent backgrounds.
05 API Reference
22 props
Prop | Type | Default | Description | |
|---|---|---|---|---|
checked | boolean | — | Current checked state. Supports two-way binding via bind:checked. | |
class | string | — | Extra classes merged onto the wrapper element. | |
disabled | boolean | — | Prevent interaction and dim the control. | |
error | string | — | Error message that replaces helper, styles the message red, and sets aria-invalid on the input. | |
helper | string | — | Hint text shown below the control. Hidden when error is set. | |
id | string | — | Explicit id to link <label> and <input>. Auto-generated if omitted. | |
indeterminate | boolean | — | Visual-only third state showing a dash icon. Resets to unchecked on next
user toggle. Does not affect the submitted form value. Supports
bind:indeterminate. | |
intent variant | dangerneutralprimarysecondary +2 more | primary | Controls the color theme and semantic meaning of the Checkbox. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. | |
label | string | — | Text label displayed to the right of the checkbox box. | |
mint | MintProp | 'none' | Micro-interaction preset applied to the box (the visible control, not
the sr-only input). Click-triggered engine mints listen on the
surrounding label; ripple ignites only on the box itself. Only
applies while not disabled. | |
name | string | — | The name attribute of the underlying <input>. Used for form submission. | |
onCheckedChange | (checked: boolean) => void | — | Fired after the checked state changes. Receives the new checked value. | |
preset | string | — | Apply a named preset registered via <BlocksProvider presets={{ Checkbox: {...} }}>.
Prefer this over class overrides when the requested look falls outside the
semantic intent palette — presets keep hover/active/dark-mode logic coherent
and make the custom look reusable across the project. | |
required | boolean | — | Mark the native input as required for form validation. | |
size variant | lgmdsmxs | md | Controls the dimensions, padding, and text size of the Checkbox. Affects the component's physical footprint. Available options: lg, md, sm, xs. | |
slotClasses | Partial<Record<CheckboxSlots, string>> | — | Per-slot class overrides merged with (or replacing, when unstyled) the
default styles. Slots: wrapper (root — what class also targets) | control |
box | icon | label | message. | |
tier | InteractiveTier | — | Semantic radius tier. Default modify — checkbox is an input-tap
surface. Inherited from TierContext when omitted; falls back to
modify outside of any tier-aware container. | |
unstyled | boolean | — | Strip all default tailwind-variants classes. Use with slotClasses for a fully custom look. The box exposes data-state for conditional styling. | |
value | string | — | The value submitted when checked. Defaults to 'on'. | |
variant variant | filledghostoutlined | outlined | Controls the visual style and presentation of the Checkbox. Determines the component's visual treatment. Available options: filled, ghost, outlined. | |
...CheckboxVariants variant | VariantProps | — | Styling variants from CheckboxVariants | |
...HTMLInputAttributes inherited | HTMLAttributes | — | HTML attributes (excluding: 'type' | 'size' | 'checked' | 'class' | 'children') |
06 Types
Local type definitions used by this component.
8 types
Name | Kind | Category | Used by | Description | |
|---|---|---|---|---|---|
CheckboxProps | interface | props | 0 | — | |
CheckboxVariants | type | variant | 0 | — | |
CheckboxSlots | type | variant | 0 | Slot names derived from the tv() config above — single source of truth for slotClasses. | |
MintProp | type | helper | 1 | — | |
InteractiveTier | type | helper | 1 | Semantic radius tier for interactive surfaces (3-tier system).
- commit → r-human (CTA, identity, status declarations)
- modify → r-interactive (fields, navigation, secondary actions)
Container components (Card, Alert, Toolbar surface, …) live in a third
tier contain (r-structure) which is **not** part of this propagation
context — those surfaces are always r-structure by design and have no
tier-flip use case. | |
MintName | type | helper | 0 | A mint name: a built-in (autocompleted), 'none' to disable, or any
consumer-registered name. (string & {}) keeps the registry open — a
custom name still type-checks, it just isn't suggested. A typo therefore
also still compiles (it resolves like an unregistered custom name and
warns at runtime); the union buys completion and docs, not validation. | |
MintConfig | interface | helper | 0 | — | |
BuiltinMintName | type | helper | 0 | Built-in mint names as a literal union, so the mint prop autocompletes
across every component — the single list the hand-curated playground knobs
and docs used to drift away from. |
07 Installation
Import
import { Checkbox } from '@urbicon-ui/blocks';