Skip to content

Latest commit

 

History

History
261 lines (211 loc) · 6.84 KB

README.md

File metadata and controls

261 lines (211 loc) · 6.84 KB

React Checkbox Pro

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

npm version npm downloads License

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