npm package: @saichandan181/react-checkbox-component
Description: A beautiful, flexible, and reusable checkbox component with exact design specifications - all states included
Author: saichandan181
Latest version: 1.0.3

# @reusable/checkbox

A beautiful, flexible, and fully accessible checkbox component for React with all interactive states.

## Features

✨ **Beautiful Design** - Modern, polished UI with smooth animations
🎨 **All States Included** - Default, Hover, Focus, and Disabled states
♿ **Fully Accessible** - WCAG compliant with proper ARIA attributes
📦 **Lightweight** - Zero dependencies (except React)
🔧 **Fully Customizable** - Extensive props for flexibility
💪 **TypeScript Support** - Full type definitions included
🚀 **Production Ready** - Optimized and battle-tested

## Installation

```bash
npm install @reusable/checkbox
```

or

```bash
yarn add @reusable/checkbox
```

or

```bash
pnpm add @reusable/checkbox
```

## Usage

### Basic Example

```tsx
import React, { useState } from 'react';
import { Checkbox } from '@reusable/checkbox';

function App() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox
      label="Accept terms and conditions"
      checked={checked}
      onChange={(e) => setChecked(e.target.checked)}
    />
  );
}
```

### Without Label

```tsx
<Checkbox
  checked={checked}
  onChange={(e) => setChecked(e.target.checked)}
  aria-label="Accept terms"
/>
```

### Disabled State

```tsx
<Checkbox
  label="Disabled checkbox"
  checked={false}
  disabled
/>

<Checkbox
  label="Disabled and checked"
  checked={true}
  disabled
/>
```

### With Form Integration

```tsx
<form onSubmit={handleSubmit}>
  <Checkbox
    name="newsletter"
    value="subscribe"
    label="Subscribe to newsletter"
    checked={formData.newsletter}
    onChange={(e) => setFormData({ ...formData, newsletter: e.target.checked })}
    required
  />
  <button type="submit">Submit</button>
</form>
```

### Controlled Component

```tsx
const [isChecked, setIsChecked] = useState(false);

<Checkbox
  label="Controlled checkbox"
  checked={isChecked}
  onChange={(e) => setIsChecked(e.target.checked)}
/>
```

### With Custom Styling

```tsx
<Checkbox
  label="Custom styled checkbox"
  checked={checked}
  onChange={(e) => setChecked(e.target.checked)}
  className="my-custom-wrapper"
  labelClassName="my-custom-label"
/>
```

### Using Ref

```tsx
const checkboxRef = useRef<HTMLInputElement>(null);

<Checkbox
  ref={checkboxRef}
  label="Checkbox with ref"
  checked={checked}
  onChange={(e) => setChecked(e.target.checked)}
/>

// Later you can access the input element
checkboxRef.current?.focus();
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | `undefined` | Label text to display next to the checkbox |
| `checked` | `boolean` | `false` | Whether the checkbox is checked |
| `disabled` | `boolean` | `false` | Whether the checkbox is disabled |
| `onChange` | `(event: ChangeEvent<HTMLInputElement>) => void` | `undefined` | Callback fired when the checkbox state changes |
| `className` | `string` | `''` | Custom className for the wrapper element |
| `labelClassName` | `string` | `''` | Custom className for the label text |
| `id` | `string` | auto-generated | ID for the input element |
| `name` | `string` | `undefined` | Name attribute for the input |
| `value` | `string` | `undefined` | Value attribute for the input |
| `required` | `boolean` | `false` | Whether the checkbox is required |
| `aria-label` | `string` | `undefined` | ARIA label for accessibility |
| `aria-describedby` | `string` | `undefined` | ARIA described by for accessibility |

All standard HTML input attributes are also supported via rest props.

## Accessibility

This component follows WCAG 2.1 guidelines and includes:

- ✅ Keyboard navigation support (Tab, Space)
- ✅ Screen reader support with proper ARIA attributes
- ✅ Focus visible states
- ✅ Semantic HTML structure
- ✅ Proper label association

## States

The checkbox includes the following visual states:

### Unselected
- **Default**: Dark cyan border (#003134), transparent background
- **Hover**: Dark cyan border with 40px circle glow (8% opacity)
- **Focus**: Dark cyan border with 40px circle glow (12% opacity)
- **Disabled**: Cyan border (#007173), reduced opacity

### Selected
- **Default**: Bright green background (#00E28B) with dark cyan checkmark (#003134)
- **Hover**: Green background with 40px circle glow (8% opacity)
- **Focus**: Green background with 40px circle glow (12% opacity)
- **Disabled**: Gray background (#7F7F7F) with light gray checkmark (#F3F6F6)

## Design Specifications

- **Size**: 18px × 18px
- **Corner Radius**: 2px
- **Checkmark**: 12px × 10px (custom SVG tick icon)
- **Interactive Area**: 40px × 40px (optimal touch target)
- **Border**: 2px solid
- **Animations**: Smooth 300ms transitions

For complete design specifications, see [SPECIFICATIONS.md](./SPECIFICATIONS.md)

## Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers (iOS Safari, Chrome Mobile)

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.