0
# RC Checkbox
1

2
RC Checkbox is a flexible, customizable checkbox UI component for React applications. It provides a comprehensive checkbox implementation with support for controlled and uncontrolled modes, custom styling, event handling, and accessibility features. The component offers three-state logic support (unchecked, checked, indeterminate) and can also function as a radio button.
3

4
## Package Information
5

6
- **Package Name**: rc-checkbox
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install rc-checkbox`
10

11
## Core Imports
12

13
```typescript
14
import Checkbox from "rc-checkbox";
15
```
16

17
For TypeScript types:
18

19
```typescript
20
import Checkbox, { type CheckboxProps, type CheckboxRef, type CheckboxChangeEvent } from "rc-checkbox";
21
```
22

23
CommonJS:
24

25
```javascript
26
const Checkbox = require("rc-checkbox");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import React, { useState } from "react";
33
import Checkbox from "rc-checkbox";
34

35
function App() {
36
  const [checked, setChecked] = useState(false);
37

38
  return (
39
    <Checkbox
40
      checked={checked}
41
      onChange={(e) => setChecked(e.target.checked)}
42
    />
43
  );
44
}
45
```
46

47
## Capabilities
48

49
### Main Component
50

51
The primary checkbox component with full TypeScript support and React forwardRef capabilities.
52

53
```typescript { .api }
54
const Checkbox: React.ForwardRefExoticComponent<
55
  CheckboxProps & React.RefAttributes<CheckboxRef>
56
>;
57
```
58

59
### Checkbox Props
60

61
Configuration interface for the checkbox component, extending HTML input attributes.
62

63
```typescript { .api }
64
interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange'> {
65
  /** CSS class prefix for styling (default: 'rc-checkbox') */
66
  prefixCls?: string;
67
  /** Custom change event handler with enhanced event object */
68
  onChange?: (e: CheckboxChangeEvent) => void;
69
}
70
```
71

72
### Event Handling
73

74
Custom event object providing additional control over event behavior.
75

76
```typescript { .api }
77
interface CheckboxChangeEvent {
78
  /** Enhanced target object with checkbox props and state */
79
  target: CheckboxChangeEventTarget;
80
  /** Stop event bubbling to parent elements */
81
  stopPropagation: () => void;
82
  /** Prevent default browser behavior */
83
  preventDefault: () => void;
84
  /** Original native change event */
85
  nativeEvent: React.ChangeEvent<HTMLInputElement>['nativeEvent'];
86
}
87

88
interface CheckboxChangeEventTarget extends CheckboxProps {
89
  /** Current checked state */
90
  checked: boolean;
91
}
92
```
93

94
### Imperative API
95

96
Ref interface for programmatic control of the checkbox.
97

98
```typescript { .api }
99
interface CheckboxRef {
100
  /** Focus the checkbox input with optional focus options */
101
  focus: (options?: FocusOptions) => void;
102
  /** Remove focus from the checkbox input */
103
  blur: () => void;
104
  /** Direct access to the underlying input element */
105
  input: HTMLInputElement | null;
106
  /** Access to the wrapper span element */
107
  nativeElement: HTMLElement | null;
108
}
109
```
110

111
## Supported Props
112

113
### Checkbox-Specific Props
114

115
- `prefixCls?: string` - CSS class prefix for custom styling (default: 'rc-checkbox')
116
- `onChange?: (e: CheckboxChangeEvent) => void` - Enhanced change event handler
117

118
### Standard HTML Input Props
119

120
- `checked?: boolean` - Controlled checked state
121
- `defaultChecked?: boolean` - Initial checked state for uncontrolled mode (default: false)
122
- `disabled?: boolean` - Disable the checkbox
123
- `name?: string` - Form field name
124
- `value?: string | number` - Form field value
125
- `className?: string` - Additional CSS classes
126
- `style?: React.CSSProperties` - Inline styles
127
- `title?: string` - Tooltip text displayed on wrapper element
128
- `type?: string` - Input type (default: 'checkbox', can be 'radio')
129
- `autoFocus?: boolean` - Auto focus on component mount
130
- `required?: boolean` - Required field validation
131
- `tabIndex?: number` - Tab navigation order
132
- `id?: string` - Unique element identifier
133
- `onFocus?: React.FocusEventHandler<HTMLInputElement>` - Focus event handler
134
- `onBlur?: React.FocusEventHandler<HTMLInputElement>` - Blur event handler
135
- `onKeyDown?: React.KeyboardEventHandler<HTMLInputElement>` - Key down event handler
136
- `onKeyPress?: React.KeyboardEventHandler<HTMLInputElement>` - Key press event handler
137
- `onKeyUp?: React.KeyboardEventHandler<HTMLInputElement>` - Key up event handler
138

139
### Accessibility & Data Attributes
140

141
- `data-*` attributes - Custom data attributes passed to input
142
- `aria-*` attributes - Accessibility attributes passed to input
143
- `role?: string` - ARIA role attribute
144

145
## Usage Examples
146

147
### Controlled Mode
148

149
```typescript
150
import React, { useState } from "react";
151
import Checkbox from "rc-checkbox";
152

153
function ControlledCheckbox() {
154
  const [checked, setChecked] = useState(false);
155

156
  return (
157
    <Checkbox
158
      checked={checked}
159
      onChange={(e) => {
160
        setChecked(e.target.checked);
161
        console.log('Checkbox is now:', e.target.checked);
162
      }}
163
    />
164
  );
165
}
166
```
167

168
### Uncontrolled Mode
169

170
```typescript
171
import React from "react";
172
import Checkbox from "rc-checkbox";
173

174
function UncontrolledCheckbox() {
175
  return (
176
    <Checkbox
177
      defaultChecked={false}
178
      onChange={(e) => {
179
        console.log('Checkbox changed to:', e.target.checked);
180
      }}
181
    />
182
  );
183
}
184
```
185

186
### With Custom Styling
187

188
```typescript
189
import React from "react";
190
import Checkbox from "rc-checkbox";
191
import "rc-checkbox/assets/index.css"; // Default styles
192

193
function StyledCheckbox() {
194
  return (
195
    <Checkbox
196
      prefixCls="my-checkbox"
197
      className="custom-checkbox"
198
      style={{ margin: '10px' }}
199
      onChange={(e) => console.log(e.target.checked)}
200
    />
201
  );
202
}
203
```
204

205
### As Radio Button
206

207
```typescript
208
import React, { useState } from "react";
209
import Checkbox from "rc-checkbox";
210

211
function RadioGroup() {
212
  const [selected, setSelected] = useState('option1');
213

214
  return (
215
    <div>
216
      <Checkbox
217
        type="radio"
218
        name="options"
219
        value="option1"
220
        checked={selected === 'option1'}
221
        onChange={(e) => setSelected(e.target.value)}
222
      />
223
      <Checkbox
224
        type="radio"
225
        name="options"
226
        value="option2"
227
        checked={selected === 'option2'}
228
        onChange={(e) => setSelected(e.target.value)}
229
      />
230
    </div>
231
  );
232
}
233
```
234

235
### Using Ref for Imperative Control
236

237
```typescript
238
import React, { useRef } from "react";
239
import Checkbox, { type CheckboxRef } from "rc-checkbox";
240

241
function RefExample() {
242
  const checkboxRef = useRef<CheckboxRef>(null);
243

244
  const focusCheckbox = () => {
245
    checkboxRef.current?.focus();
246
  };
247

248
  const blurCheckbox = () => {
249
    checkboxRef.current?.blur();
250
  };
251

252
  return (
253
    <div>
254
      <Checkbox ref={checkboxRef} />
255
      <button onClick={focusCheckbox}>Focus Checkbox</button>
256
      <button onClick={blurCheckbox}>Blur Checkbox</button>
257
    </div>
258
  );
259
}
260
```
261

262
### Advanced Event Handling
263

264
```typescript
265
import React from "react";
266
import Checkbox from "rc-checkbox";
267

268
function AdvancedEventHandling() {
269
  const handleChange = (e) => {
270
    // Prevent the change from bubbling up
271
    e.stopPropagation();
272
    
273
    // Access all checkbox props and state
274
    console.log('Target props:', e.target);
275
    console.log('Checked state:', e.target.checked);
276
    console.log('Native event:', e.nativeEvent);
277
  };
278

279
  return (
280
    <div onClick={() => console.log('Div clicked')}>
281
      <Checkbox onChange={handleChange} />
282
    </div>
283
  );
284
}
285
```
286

287
## CSS Classes
288

289
The component generates the following CSS classes for styling:
290

291
- `rc-checkbox` - Base wrapper class (or custom `prefixCls`)
292
- `rc-checkbox-checked` - Applied when checked state is true
293
- `rc-checkbox-disabled` - Applied when disabled prop is true
294
- `rc-checkbox-input` - Applied to the input element
295
- `rc-checkbox-inner` - Applied to the inner visual element
296

297
## Browser Compatibility
298

299
- IE11, Edge
300
- Firefox (last 2 versions)
301
- Chrome (last 2 versions)
302
- Safari (last 2 versions)
303
- Electron (last 2 versions)
304

305
## Dependencies
306

307
- **classnames** - CSS class management utility
308
- **rc-util** - Utilities including `useMergedState` hook
309
- **React 16.9+** - Peer dependency