Checkbox

Installation

npx usmds add checkbox

Usage

import { Checkbox } from '@components/Checkbox';
import { useState } from 'react';
 
function App() {
  const [checked, setChecked] = useState(false);
 
  return (
    <Checkbox 
      label="Checkbox item"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

Props

Checkbox

Extends CheckboxPrimitive.Root props.

Prop	Type	Default	Description
label	`string`	-	The text label for the checkbox.
checked	`boolean`	`false`	The controlled checked state of the checkbox.
onCheckedChange	`(checked: boolean) => void`	-	Callback that fires when the checked state changes.
disabled	`boolean`	`false`	When true, prevents the user from interacting with the checkbox.
className	`string`	-	Additional Tailwind classes to apply.

Examples

Default State

<Checkbox 
  label="Checkbox item" 
  checked={false} 
  onCheckedChange={setChecked} 
/>

Checked State

<Checkbox 
  label="Checkbox item" 
  checked={true} 
  onCheckedChange={setChecked} 
/>

Disabled States

// Disabled unchecked
<Checkbox 
  label="Disabled unchecked" 
  checked={false} 
  disabled 
  onCheckedChange={() => {}} 
/>
 
// Disabled checked
<Checkbox 
  label="Disabled checked" 
  checked={true} 
  disabled 
  onCheckedChange={() => {}} 
/>

Styling

The Checkbox component uses Tailwind CSS classes for styling. Default styling includes:

Container dimensions: 329px × 20px
Checkbox dimensions: 24px × 24px
2px border width
Rounded corners (2px)
Primary color when checked
Disabled state styling
8px gap between checkbox and label

State Management

The component uses controlled state pattern:

import { useState } from 'react';
 
function CheckboxExample() {
  const [checked, setChecked] = useState(false);
 
  return (
    <Checkbox
      label="Controlled checkbox"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

Accessibility

The Checkbox component:

Uses accessibilityRole="checkbox" for proper semantic structure
Supports keyboard navigation
Maintains WCAG color contrast requirements
Provides appropriate accessibilityState for checked and disabled states
Includes clear, descriptive text labels

Checkbox

On this page