components / checkbox

Checkbox

Accessible checkbox with label, helper and error text, an indeterminate state and colors.

How to use

A native `<input type="checkbox">` (so forms, `ref` and keyboard just work) with a custom look. Pass `label` to make the whole row clickable, and `indeterminate` for a parent that has only some children checked.

preview

Accept the terms

NewsletterOne email per week

Select all

Checkbox.tsx

import { Checkbox } from "vaiperui";
 
<Checkbox label="Accept the terms" />
<Checkbox
  defaultChecked
  label="Newsletter"
  helperText="One email per week"
/>
<Checkbox indeterminate label="Select all" />

Colors

preview

primary

success

warning

danger

colors.tsx

<Checkbox defaultChecked variantColor="primary" label="primary" />
<Checkbox defaultChecked variantColor="success" label="success" />
<Checkbox defaultChecked variantColor="warning" label="warning" />
<Checkbox defaultChecked variantColor="danger" label="danger" />

Sizes

preview

sizes.tsx

<Checkbox defaultChecked size="sm" label="sm" />
<Checkbox defaultChecked size="md" label="md" />
<Checkbox defaultChecked size="lg" label="lg" />

Indeterminate

`indeterminate` shows a dash, for a parent checkbox with only some children checked.

preview

Select all

indeterminate

indeterminate.tsx

<Checkbox indeterminate label="Select all" />

States

preview

helperExtra detail

helper

errorThis is required

error

disabled

disabled ✓

states.tsx

<Checkbox label="helper" helperText="..." />
<Checkbox label="error" errorMessage="..." />
<Checkbox label="disabled" disabled />
<Checkbox label="disabled" disabled defaultChecked />

Custom color

`customColor` takes any CSS color, or a `{ light, dark }` pair.

preview

Orange

Violet

custom-color.tsx

<Checkbox defaultChecked customColor="#ff6600" label="Orange" />
<Checkbox defaultChecked customColor={{ light: "#7c3aed", dark: "#a78bfa" }} label="Violet" />

Props

Prop	Values	Default	Description
variantColor	primary \| success \| warning \| danger	primary	Color of the checked state and focus ring
customColor	string \| { light, dark }	none	Any CSS color (or a pair per theme). Overrides variantColor
size	sm \| md \| lg	md	Size of the control and its text
radius	none \| sm \| md \| lg \| full	sm	Corner rounding of the box
animation	none \| smooth \| fast \| bounce	smooth	Transition when it toggles
label	ReactNode	none	Text next to the control; clicking it toggles
helperText	string	none	Secondary line under the label
errorMessage	string	none	Error text; its presence alone forces the error state
indeterminate	boolean	false	Shows a dash instead of the check
(native)	InputHTMLAttributes<HTMLInputElement>	none	checked, defaultChecked, onChange, name, value, disabled, required, aria-*, className, ref, etc.

Accessibility

Renders a native `<input type="checkbox">` (visually hidden, drawn over by the custom box), so role, Space toggle and form behavior are native.
The `<label>` wraps the input, so the label text names it and the whole row is clickable.
`indeterminate` sets the DOM `indeterminate` property, which assistive tech reads as "mixed".
`errorMessage` sets `aria-invalid="true"`; `aria-describedby` points to the error, or to `helperText` when there is no error.
The check and dash icons are `aria-hidden`; state is exposed only by the native input.

Keyboard

Key	Action
Space	Toggles the checkbox.

Keep in mind

Without `label`, pass `aria-label`; the control has no other name.
`indeterminate` is visual state only: clicking still resolves to checked or unchecked, and you decide what that means.