React Checkbox Pro

A fully accessible, customizable React checkbox component with indeterminate state support, keyboard shortcuts, and modern styling.

Features

• 🎨 Multiple color variants and sizes
• ♿️ Fully accessible (WAI-ARIA compliant)
• 📱 Responsive and mobile-friendly
• 🎯 Indeterminate state support
• 🎭 Custom icons support
• 💅 Tailwind CSS styling
• 📝 TypeScript support
• 🔧 Highly customizable
• ⌨️ Keyboard shortcuts support
• 🎉 Easy to use
• 🔄 Controlled & Uncontrolled modes
• 👥 Checkbox group support
• 📍 Flexible label placement

Installation

npm install react-checkbox-pro
# or
yarn add react-checkbox-pro
# or
pnpm add react-checkbox-pro

Quick Start

import { Checkbox } from 'react-checkbox-pro';

function App() {
  return (
    <Checkbox defaultChecked>
      Click me
    </Checkbox>
  );
}

Usage

Basic Usage

// Controlled
const [checked, setChecked] = useState(false);

<Checkbox
  checked={checked}
  onChange={setChecked}
  helperText="Optional helper text"
>
  Accept terms and conditions
</Checkbox>

// Uncontrolled
<Checkbox
  defaultChecked
  onChange={(checked) => console.log(checked)}
>
  Remember me
</Checkbox>

Color Variants

<Checkbox color="default">Default</Checkbox>
<Checkbox color="primary">Primary</Checkbox>
<Checkbox color="secondary">Secondary</Checkbox>
<Checkbox color="success">Success</Checkbox>
<Checkbox color="warning">Warning</Checkbox>
<Checkbox color="danger">Danger</Checkbox>

Size Variants

<Checkbox size="xs">Extra Small</Checkbox>
<Checkbox size="sm">Small</Checkbox>
<Checkbox size="md">Medium</Checkbox>
<Checkbox size="lg">Large</Checkbox>

Label Placement

<Checkbox labelPlacement="left">Left Label</Checkbox>
<Checkbox labelPlacement="right">Right Label</Checkbox>
<Checkbox labelPlacement="top">Top Label</Checkbox>
<Checkbox labelPlacement="bottom">Bottom Label</Checkbox>

With Error State

<Checkbox
  error={true}
  errorMessage="This field is required"
  required
>
  Accept terms and conditions
</Checkbox>

With Keyboard Shortcuts

<Checkbox
  shortcut="ctrl+1"
  onShortcut={() => console.log('Shortcut triggered')}
>
  Toggle with Ctrl+1
</Checkbox>

Checkbox Group

function App() {
  const [selected, setSelected] = useState(['apple']);

  return (
    <CheckboxGroup
      value={selected}
      onChange={setSelected}
      orientation="vertical"
    >
      <Checkbox value="apple">Apple</Checkbox>
      <Checkbox value="banana">Banana</Checkbox>
      <Checkbox value="orange">Orange</Checkbox>
    </CheckboxGroup>
  );
}

Indeterminate State Example

function TodoList() {
  const [todos, setTodos] = useState([
    { id: 1, title: "Task 1", completed: false },
    { id: 2, title: "Task 2", completed: false },
  ]);

  const allSelected = todos.every((todo) => todo.completed);
  const someSelected = todos.some((todo) => todo.completed);
  const isIndeterminate = someSelected && !allSelected;

  const handleParentChange = (checked) => {
    setTodos((prev) => prev.map((todo) => ({
      ...todo,
      completed: checked,
    })));
  };

  return (
    <div>
      <Checkbox
        checked={allSelected}
        indeterminate={isIndeterminate}
        onChange={handleParentChange}
      >
        Select All
      </Checkbox>
      
      {todos.map((todo) => (
        <Checkbox
          key={todo.id}
          checked={todo.completed}
          onChange={(checked) => handleTodoChange(todo.id, checked)}
        >
          {todo.title}
        </Checkbox>
      ))}
    </div>
  );
}

Custom Icons

import { CircleIcon, CheckIcon } from './icons';

<Checkbox
  icon={<CircleIcon />}
  checkedIcon={<CheckIcon />}
>
  Custom Icons
</Checkbox>

Props

Checkbox Props

Prop	Type	Default	Description
checked	boolean	undefined	Controlled checked state
defaultChecked	boolean	false	Default checked state for uncontrolled component
onChange	(checked: boolean) => void | (event: ChangeEvent) => void	undefined	Change handler
disabled	boolean	false	Whether the checkbox is disabled
required	boolean	false	Whether the checkbox is required
error	boolean	false	Whether to show error state
errorMessage	string	undefined	Error message to display
helperText	string	undefined	Helper text to display
indeterminate	boolean	false	Whether to show indeterminate state
size	'xs' | 'sm' | 'md' | 'lg'	'md'	Size of the checkbox
color	'default' | 'primary' | 'secondary' | 'success' | 'warning' | 'danger'	'primary'	Color variant
radius	'none' | 'sm' | 'md' | 'lg' | 'full'	'md'	Border radius variant
labelPlacement	'left' | 'right' | 'top' | 'bottom'	'right'	Label placement
icon	ReactNode	undefined	Custom unchecked icon
checkedIcon	ReactNode	undefined	Custom checked icon
shortcut	string	undefined	Keyboard shortcut (e.g., 'ctrl+1')
onShortcut	() => void	undefined	Shortcut callback

CheckboxGroup Props

Prop	Type	Default	Description
value	string[]	undefined	Controlled selected values
defaultValue	string[]	[]	Default selected values
onChange	(values: string[]) => void	undefined	Change handler
disabled	boolean	false	Disable all checkboxes in group
orientation	'horizontal' | 'vertical'	'vertical'	Layout orientation
spacing	'sm' | 'md' | 'lg'	'md'	Space between checkboxes
labelPlacement	'left' | 'right' | 'top' | 'bottom'	'right'	Label placement for all checkboxes

Accessibility

The component is built with accessibility in mind and follows WAI-ARIA guidelines:

• Proper ARIA attributes (aria-checked, aria-invalid, etc.)
• Keyboard navigation support
• Screen reader friendly
• Clear focus indicators
• Proper labeling and descriptions

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT © Md Habibur Rahman

Support

• Create an Issue
• Follow on Twitter
• Star the repo ⭐️