Checkbox

Overview

The Checkbox is the canonical form input for zero-or-more selections. Reach for it whenever the user can pick any combination of options independently. For exactly one selection in a small known set, use a Radio group instead. For binary settings that take effect immediately (notifications on / off), reach for a Switch.

States

Nine visible states. Hover, active, and focus are pseudo-class driven — they come for free on the real component. Held still here for review.

Compositions

Four canonical compositions cover almost every form. Reach for the one that fits the surface — don't invent a fifth.

Groups

Wrap related checkboxes in a <fieldset> with a <legend> (visible or visually hidden) so screen readers announce the group's purpose. A parent row with indeterminate can summarise the children — toggling it flips all of them.

Anatomy

Five named parts. Only the box is required — label, description, and error message are opt-in.

Behavior

• 01Click target is the whole row. Clicking the label toggles the box — the native <label htmlFor> association handles it. Don't intercept clicks on the label.
• 02Keyboard activates on Space. Native button-input convention — Space toggles, Tab moves focus. Don't hijack with custom handlers.
• 03Indeterminate clears on toggle. When the user clicks an indeterminate parent, it commits to a definite state (true or false) — never returns to indeterminate from a click. The component handles this for uncontrolled use.
• 04Form submission is native. The component renders a real <input type="checkbox"> under the hood — pass name and the value posts with the form, no extra wiring needed.
• 05Transitions are colour-only. The border and background tweak in 150 ms — no scale, no ripple, no glow. The same restraint as the Button.

Accessibility

• Native semantics. The component renders an <input type="checkbox"> inside a <label> via htmlFor. No custom ARIA — the platform already does this well.
• Description and error messages are linked via aria-describedby so screen readers announce them after the label.
• Invalid state sets aria-invalid="true" on the input when the error prop is set, so assistive tech announces the failure as well as the message.
• Focus ring is the system ring — 2 px #9EB7FF with 2 px offset, drawn via peer-focus-visible so it only appears for keyboard users.
• Group containers. Wrap related checkboxes in a <fieldset> with a <legend> (visible or sr-only) so the group's purpose is announced before the first item.

Code

Import from @flatpay-dk/ui. Renders a real native input — every standard checkbox attribute passes through (name, required, form, etc.).

import { Checkbox } from "@flatpay-dk/ui";

// Default — uncontrolled, label only
<Checkbox label="Send me product updates" />

// Label + help text
<Checkbox
  label="Subscribe to weekly digest"
  description="Curated highlights — no marketing fluff."
/>

// Controlled
<Checkbox
  checked={notifications}
  onCheckedChange={setNotifications}
  label="Notifications enabled"
/>

// Indeterminate (parent row)
<Checkbox
  checked={allOn ? true : someOn ? "indeterminate" : false}
  onCheckedChange={setAll}
  label="All sections"
/>

// Invalid + error message
<Checkbox
  label="I agree to the merchant terms"
  description="Required to continue."
  error="Please confirm before proceeding."
/>

// In a form — native submission, no extra wiring
<form action={submit}>
  <Checkbox name="marketing_opt_in" label="Marketing emails" />
  <Button type="submit">Continue</Button>
</form>

Best practices

The Checkbox is everywhere. A few habits keep it predictable.

Props

Related