https://github.com/shakibdshy/react-checkbox-pro
A flexible and feature-rich checkbox component for React applications with TailwindCSS support.
https://github.com/shakibdshy/react-checkbox-pro
checkbox checkbox-component checkbox-group checkboxlist custom custom-icon-with-checkbox headless-checkbox react-checkbox tailwind-checkbox
Last synced: 1 day ago
JSON representation
A flexible and feature-rich checkbox component for React applications with TailwindCSS support.
- Host: GitHub
- URL: https://github.com/shakibdshy/react-checkbox-pro
- Owner: shakibdshy
- Created: 2025-01-03T17:56:28.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2025-02-12T08:14:40.000Z (over 1 year ago)
- Last Synced: 2025-08-28T06:04:45.988Z (11 months ago)
- Topics: checkbox, checkbox-component, checkbox-group, checkboxlist, custom, custom-icon-with-checkbox, headless-checkbox, react-checkbox, tailwind-checkbox
- Language: TypeScript
- Homepage: https://react-packages-doc.vercel.app/docs/react-checkbox-pro
- Size: 431 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# React Checkbox Pro
A fully accessible, customizable React checkbox component with indeterminate state support, keyboard shortcuts, and modern styling.
[](https://www.npmjs.com/package/react-checkbox-pro)
[](https://www.npmjs.com/package/react-checkbox-pro)
[](https://github.com/yourusername/react-checkbox-pro/blob/main/LICENSE)
## 📚 Demo & Documentation
[Documentation](https://react-packages-doc.vercel.app/)
## 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
```bash
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`:
```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
```jsx
import { Checkbox } from 'react-checkbox-pro';
function App() {
return (
Click me
);
}
```
### Color Variants
```jsx
Default
Primary
Secondary
Success
Warning
Danger
```
### Size Variants
```jsx
Extra Small
Small
Medium
Large
```
### Label Placement
```jsx
Left Label
Right Label
Top Label
Bottom Label
```
### With Error State
```jsx
Accept terms and conditions
```
### Controlled and Uncontrolled
```jsx
// Controlled
const [checked, setChecked] = useState(false);
Accept terms and conditions
// Uncontrolled
console.log(checked)}
>
Remember me
```
### With Keyboard Shortcuts
```jsx
console.log('Shortcut triggered')}
>
Toggle with Ctrl+1
```
### Checkbox Group
```jsx
function App() {
const [selected, setSelected] = useState(['apple']);
return (
Apple
Banana
Orange
);
}
```
### Indeterminate State Example
```jsx
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 (
Select All
{todos.map((todo) => (
handleTodoChange(todo.id, checked)}
>
{todo.title}
))}
);
}
```
### Custom Icons
```jsx
import { CircleIcon, CheckIcon } from './icons';
}
checkedIcon={}
>
Custom Icons
```
## 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](CONTRIBUTING.md) for details.
## License
MIT © [Md Habibur Rahman](https://github.com/shakibdshy)
## Support
- Create an [Issue](https://github.com/shakibdshy/react-checkbox-pro/issues)
- Follow on [Twitter](https://twitter.com/shakibdshy)
- Star the repo ⭐️