React-checkbox-pro NPM

React Checkbox Pro

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

📚 Demo & Documentation

Documentation

Features

Core Features

✨ Modern, lightweight checkbox component
🔄 Controlled & Uncontrolled modes support
👥 Checkbox group for managing multiple selections
🎯 Indeterminate state support
⌨️ Full keyboard navigation and shortcuts
🎨 CSS-in-JS with Tailwind variants

Styling & Customization

🎭 Custom icons support
🖼️ Built-in check and indeterminate icons
🎨 Multiple built-in color variants
Default, Primary, Secondary, Success, Warning, Danger
📐 Four size variants (xs, sm, md, lg)
🔲 Configurable border radius
📍 Flexible label placement (left, right, top, bottom)
💅 Works with both Tailwind CSS and custom CSS
🎯 Custom styles without breaking accessibility
🎪 Compound variants support

Accessibility & UX

♿️ WAI-ARIA 1.2 compliant
🔍 Screen reader friendly
🎯 Focus management and indicators
💬 Support for helper text and error messages
📱 Responsive and touch-friendly
🖱️ Click area optimization
🔄 Smooth transitions

Developer Experience

📝 Written in TypeScript with full type definitions
🏃‍♂️ Tree-shakeable and optimized bundle
📚 Comprehensive documentation and examples
🧪 Reliable with proper error handling
🔧 Easy to integrate and customize
🎁 Zero external runtime dependencies
📦 Small bundle size
🔍 Source maps included

Advanced Features

🔑 Keyboard shortcuts customization
🎛️ Form integration support
🔄 Async state management
🎨 Theme customization support
🔒 Disabled and readonly states
📊 Group selection management
🎯 Compound variants for complex styling
🎨 CSS variables support
🔄 State persistence options
🎨 Custom styles without breaking accessibility

Installation

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

Usage

Add the plugin to your tailwind.config.js:

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@shakibdshy/tailwind-theme/dist/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  plugins: [
    require('@shakibdshy/tailwind-theme')
  ],
}

Quick Start

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

function App() {
  return (
    <Checkbox defaultChecked>
      Click 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>

Controlled and Uncontrolled

// 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>

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