Zentauri UI
Forms

Checkboxes for form selection

Checkboxes let people select one or more independent options. Zentauri UI ships a standalone Checkbox primitive so forms can use dedicated state, label, size, appearance, and indeterminate APIs instead of the generic Input fallback.

Examples

Use the animated entrypoint when the check mark should draw in as state changes.

Checkbox variants examples

Checkbox exposes dedicated appearance, size, indeterminate, controlled, and animated APIs without going through the generic Input component.

Appearance: DEFAULT | Size: MD

Appearance: SUCCESS | Size: MD

Appearance: WARNING | Size: MD

Appearance: ERROR | Size: MD

Appearance: INFO | Size: MD

Appearance: VIOLET | Size: MD

Appearance: AMBER | Size: MD

Appearance: PINK | Size: MD

Appearance: INDIGO | Size: MD

Appearance: VIOLET | Size: SM

Appearance: VIOLET | Size: MD

Appearance: VIOLET | Size: LG

Appearance: INFO | Size: md | Indeterminate: TRUE - The indeterminate state is a visual-only condition for HTML checkboxes where the input appears neither checked nor unchecked, typically displayed as a horizontal dash (—) or a filled square.

CSS variable overrides

Checkbox CSS variables

Override these checkbox variables on :root, a theme selector, or a component wrapper.

38 variables

Pattern: --zui-<component>-<slot?>-<variant?>-<property>-<state?>-dark?

:root {
  --zui-checkbox-label-fg: oklch(20.8% 0.042 265.755);
  --zui-checkbox-border: #0000004d;
  --zui-checkbox-bg: transparent;
  --zui-checkbox-fg: oklch(44.6% 0.043 257.281);
  --zui-checkbox-ring-focus: oklch(44.6% 0.043 257.281 / 0.7);
  --zui-checkbox-ring-offset-focus: oklch(98.4% 0.003 247.858);
  --zui-checkbox-default-border-checked: oklch(44.6% 0.043 257.281);
  --zui-checkbox-default-bg-checked: oklch(44.6% 0.043 257.281);
  --zui-checkbox-default-fg-checked: #ffffff;
  --zui-checkbox-success-border-checked: oklch(59.6% 0.145 163.225);
  --zui-checkbox-success-bg-checked: oklch(59.6% 0.145 163.225);
  --zui-checkbox-success-fg-checked: #ffffff;
  --zui-checkbox-warning-border-checked: oklch(68.1% 0.162 75.834);
  --zui-checkbox-warning-bg-checked: oklch(68.1% 0.162 75.834);
  --zui-checkbox-warning-fg-checked: #ffffff;
  --zui-checkbox-error-border-checked: oklch(58.6% 0.253 17.585);
  --zui-checkbox-error-bg-checked: oklch(58.6% 0.253 17.585);
  --zui-checkbox-error-fg-checked: #ffffff;
  --zui-checkbox-info-border-checked: oklch(54.6% 0.245 262.881);
  --zui-checkbox-info-bg-checked: oklch(54.6% 0.245 262.881);
  --zui-checkbox-info-fg-checked: #ffffff;
  --zui-checkbox-violet-border-checked: oklch(54.1% 0.281 293.009);
  --zui-checkbox-violet-bg-checked: oklch(54.1% 0.281 293.009);
  --zui-checkbox-violet-fg-checked: #ffffff;
  --zui-checkbox-amber-border-checked: oklch(66.6% 0.179 58.318);
  --zui-checkbox-amber-bg-checked: oklch(66.6% 0.179 58.318);
  --zui-checkbox-amber-fg-checked: #ffffff;
  --zui-checkbox-pink-border-checked: oklch(59.2% 0.249 0.584);
  --zui-checkbox-pink-bg-checked: oklch(59.2% 0.249 0.584);
  --zui-checkbox-pink-fg-checked: #ffffff;
  --zui-checkbox-indigo-border-checked: oklch(51.1% 0.262 276.966);
  --zui-checkbox-indigo-bg-checked: oklch(51.1% 0.262 276.966);
  --zui-checkbox-indigo-fg-checked: #ffffff;
}

/* Dark theme variables follow the same names with -dark appended. */
.dark {
  --zui-checkbox-label-fg-dark: oklch(98.4% 0.003 247.858);
  --zui-checkbox-border-dark: #ffffff4d;
}

What it does

Expose a label-friendly checkbox primitive with checked, unchecked, and mixed states.

Use it for independent selections, not mutually exclusive choices.

Composition and API

Import Checkbox from the dedicated checkbox entrypoint. Use appearance and size variants for visual tone, and use rootClassName or controlClassName when you need slot-level styling.

Common use cases

  • Terms acceptance in onboarding and checkout flows.
  • Bulk selection with a parent indeterminate state.
  • Notification and preference lists.
  • Feature permissions in admin settings.

Accessibility

The component renders a native checkbox input with visible label composition. Provide a text label or aria-label, and reserve indeterminate state for partial selection.

Next.js integration notes

Use Checkbox inside client components when state changes in the browser. Static defaultChecked examples can still be colocated with App Router preview pages.

FAQ

Does Checkbox support indeterminate state?

Yes. Pass indeterminate to render the mixed visual state and aria-checked=mixed for assistive technology.

Can I control Checkbox state from React?

Yes. Use checked with onCheckedChange for controlled state, or defaultChecked for uncontrolled state.

Is there an animated Checkbox?

Yes. Import CheckboxAnimated from the animated entrypoint to animate the checkmark or mixed-state indicator.