Checkbox

A control that allows users to select one or more items from a set

Installation

pnpm add @wandercom/design-system-web

Usage

import { Checkbox } from '@wandercom/design-system-web/ui/checkbox';
import { Label } from '@wandercom/design-system-web/ui/label';

export function Example() {
  return (
    <div className="flex items-center gap-2.5">
      <Checkbox id="terms" />
      <Label htmlFor="terms">
        Accept terms and conditions
      </Label>
    </div>
  );
}

Examples

Default

Loading example...
<div className="flex flex-col gap-6">
  <div className="flex items-center gap-2.5">
    <Checkbox id="unchecked" />
    <Label htmlFor="unchecked">Accept terms and conditions</Label>
  </div>

  <div className="flex items-center gap-2.5">
    <Checkbox defaultChecked id="checked" />
    <Label htmlFor="checked">Accept terms and conditions</Label>
  </div>

  <div className="flex items-center gap-2.5">
    <Checkbox disabled id="disabled-unchecked" />
    <Label htmlFor="disabled-unchecked">Disabled checkbox</Label>
  </div>

  <div className="flex items-center gap-2.5">
    <Checkbox defaultChecked disabled id="disabled-checked" />
    <Label htmlFor="disabled-checked">Disabled checked checkbox</Label>
  </div>
</div>

With text

Loading example...
<div className="flex max-w-md flex-col gap-6">
  <div className="flex items-start gap-2.5">
    <Checkbox className="mt-0.5" id="marketing" />
    <div className="flex flex-col gap-1">
      <Label htmlFor="marketing">Marketing emails</Label>
      <p className="text-secondary text-sm">
        Receive emails about new properties and special offers
      </p>
    </div>
  </div>

  <div className="flex items-start gap-2.5">
    <Checkbox className="mt-0.5" defaultChecked id="notifications" />
    <div className="flex flex-col gap-1">
      <Label htmlFor="notifications">Push notifications</Label>
      <p className="text-secondary text-sm">
        Get notified when new properties match your preferences
      </p>
    </div>
  </div>
</div>

Props

defaultChecked?

boolean
The default checked state when the component is first rendered.

checked?

boolean | 'indeterminate'
The controlled checked state. Supports indeterminate for partially selected groups.

onCheckedChange?

(checked: boolean | 'indeterminate') => void
Callback fired when the checked state changes.

disabled?

boolean
Disables the checkbox when true.

required?

boolean
Makes the checkbox required in forms.

name?

string
The name of the checkbox for form submission.

value?

string
The value used for form submission.

id?

string
ID for associating with a label element.

className?

string
Additional CSS classes to apply.

Accessibility

The Checkbox component is built on the Radix UI Checkbox primitive, which provides full WAI-ARIA compliance out of the box.

  • Renders as role="checkbox" with proper aria-checked state management, including support for the mixed state when indeterminate
  • Supports keyboard interaction: Space toggles the checked state
  • Use a Label component with a matching htmlFor and id to associate a visible label with the checkbox
  • Focus is indicated with a visible ring for keyboard navigation
  • Disabled checkboxes apply aria-disabled and reduce opacity to communicate their state visually
Checkbox