0
# RC Input Number
1

2
RC Input Number is a React component that provides a comprehensive numeric input field with built-in increment/decrement controls, validation, formatting, and accessibility features. It supports both controlled and uncontrolled usage patterns with extensive customization options for styling and behavior.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import InputNumber from "rc-input-number";
15
import type { InputNumberProps, ValueType } from "rc-input-number";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const InputNumber = require("rc-input-number");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import React from "react";
28
import InputNumber from "rc-input-number";
29

30
// Simple usage
31
function SimpleExample() {
32
  return <InputNumber defaultValue={10} />;
33
}
34

35
// Controlled component with constraints
36
function ControlledExample() {
37
  const [value, setValue] = React.useState<number | null>(5);
38
  
39
  return (
40
    <InputNumber
41
      min={0}
42
      max={100}
43
      step={1}
44
      value={value}
45
      onChange={(val) => setValue(val)}
46
      precision={2}
47
    />
48
  );
49
}
50

51
// With custom formatting
52
function FormattedExample() {
53
  return (
54
    <InputNumber
55
      defaultValue={1000}
56
      formatter={(value) => `$ ${value}`.replace(/\B(?=(\d{3})+(?!\d))/g, ',')}
57
      parser={(value) => value?.replace(/\$\s?|(,*)/g, '') || ''}
58
    />
59
  );
60
}
61
```
62

63
## Capabilities
64

65
### Core Component
66

67
The main InputNumber component provides a complete numeric input solution with step controls and validation.
68

69
```typescript { .api }
70
const InputNumber: <T extends ValueType = ValueType>(
71
  props: React.PropsWithChildren<InputNumberProps<T>> & {
72
    ref?: React.Ref<HTMLInputElement>;
73
  }
74
) => React.ReactElement;
75

76
type ValueType = string | number;
77
```
78

79
### Component Props Interface
80

81
Complete props interface for the InputNumber component.
82

83
```typescript { .api }
84
interface InputNumberProps<T extends ValueType = ValueType>
85
  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 
86
    'value' | 'defaultValue' | 'onInput' | 'onChange' | 'prefix' | 'suffix'> {
87
  
88
  // Value Management
89
  /** Controlled value of the input */
90
  value?: T | null;
91
  /** Initial uncontrolled value */
92
  defaultValue?: T;
93
  /** Whether to return string values instead of numbers */
94
  stringMode?: boolean;
95

96
  // Numeric Constraints
97
  /** Minimum allowed value */
98
  min?: T;
99
  /** Maximum allowed value */
100
  max?: T;
101
  /** Step increment value (default: 1) */
102
  step?: ValueType;
103
  /** Number of decimal places to display */
104
  precision?: number;
105

106
  // Styling & Layout
107
  /** CSS class prefix (default: 'rc-input-number') */
108
  prefixCls?: string;
109
  /** Additional CSS classes */
110
  className?: string;
111
  /** Inline styles */
112
  style?: React.CSSProperties;
113
  /** Granular class names for sub-components */
114
  classNames?: BaseInputProps['classNames'] & {
115
    input?: string;
116
  };
117

118
  // Content Decorators
119
  /** Element before the input */
120
  prefix?: React.ReactNode;
121
  /** Element after the input */
122
  suffix?: React.ReactNode;
123
  /** Element before the entire control */
124
  addonBefore?: React.ReactNode;
125
  /** Element after the entire control */
126
  addonAfter?: React.ReactNode;
127

128
  // Step Controls
129
  /** Whether to show up/down buttons (default: true) */
130
  controls?: boolean;
131
  /** Custom up button element */
132
  upHandler?: React.ReactNode;
133
  /** Custom down button element */
134
  downHandler?: React.ReactNode;
135

136
  // Input Processing
137
  /** Format value for display */
138
  formatter?: (value: T | undefined, info: { userTyping: boolean; input: string }) => string;
139
  /** Parse display value to actual value */
140
  parser?: (displayValue: string | undefined) => T;
141
  /** Custom decimal separator character */
142
  decimalSeparator?: string;
143
  /** Regex pattern for input validation (useful for iOS number pad) */
144
  pattern?: string;
145
  /** Input mode attribute for mobile keyboards */
146
  inputMode?: string;
147

148
  // Interaction Controls
149
  /** Enable keyboard arrow key controls */
150
  keyboard?: boolean;
151
  /** Enable mouse wheel value changes */
152
  wheel?: boolean;
153
  /** Whether to trigger onChange on blur (default: true) */
154
  changeOnBlur?: boolean;
155
  /** Disable the input */
156
  disabled?: boolean;
157
  /** Make input read-only */
158
  readOnly?: boolean;
159
  /** Required field validation */
160
  required?: boolean;
161
  /** Auto focus the input on mount */
162
  autoFocus?: boolean;
163
  /** Tab index for keyboard navigation */
164
  tabIndex?: number;
165
  /** HTML name attribute */
166
  name?: string;
167
  /** HTML id attribute */
168
  id?: string;
169
  /** Placeholder text */
170
  placeholder?: string;
171

172
  // Event Handlers
173
  /** Value change callback */
174
  onChange?: (value: T | null) => void;
175
  /** Input text change callback */
176
  onInput?: (text: string) => void;
177
  /** Enter key press handler */
178
  onPressEnter?: React.KeyboardEventHandler<HTMLInputElement>;
179
  /** Focus event handler */
180
  onFocus?: React.FocusEventHandler<HTMLInputElement>;
181
  /** Blur event handler */
182
  onBlur?: React.FocusEventHandler<HTMLInputElement>;
183
  /** Click event handler */
184
  onClick?: React.MouseEventHandler<HTMLInputElement>;
185
  /** Step button interaction callback */
186
  onStep?: (value: T, info: { offset: ValueType; type: 'up' | 'down' }) => void;
187
}
188
```
189

190
### Value Type Definition
191

192
Union type representing acceptable numeric value types.
193

194
```typescript { .api }
195
type ValueType = string | number;
196

197
// From rc-input BaseInputProps interface
198
interface BaseInputProps {
199
  classNames?: {
200
    affixWrapper?: string;
201
    prefix?: string;
202
    suffix?: string;
203
    groupWrapper?: string;
204
    wrapper?: string;
205
  };
206
}
207
```
208

209
### Advanced Usage Examples
210

211
#### Precision Control and Formatting
212

213
```typescript
214
// Currency input with precise decimal handling
215
<InputNumber
216
  defaultValue={99.99}
217
  precision={2}
218
  step={0.01}
219
  formatter={(value) => `$ ${value}`}
220
  parser={(value) => value?.replace(/\$\s?/g, '') || ''}
221
  min={0}
222
/>
223

224
// Percentage input
225
<InputNumber
226
  defaultValue={50}
227
  min={0}
228
  max={100}
229
  formatter={(value) => `${value}%`}
230
  parser={(value) => value?.replace('%', '') || ''}
231
/>
232
```
233

234
#### String Mode for High Precision
235

236
```typescript
237
// Using string mode for very large or precise numbers
238
<InputNumber
239
  stringMode
240
  defaultValue="123456789012345678901234567890.123456789"
241
  precision={9}
242
  onChange={(value) => {
243
    // value is string in stringMode
244
    console.log(typeof value); // "string"
245
  }}
246
/>
247
```
248

249
#### Custom Step Handlers and Validation
250

251
```typescript
252
function CustomStepExample() {
253
  const [value, setValue] = React.useState<number>(0);
254
  
255
  const handleStep = (newValue: number, info: { offset: ValueType; type: 'up' | 'down' }) => {
256
    console.log(`Stepped ${info.type} by ${info.offset}`);
257
    // Custom validation logic
258
    if (newValue >= 0 && newValue <= 1000) {
259
      setValue(newValue);
260
    }
261
  };
262
  
263
  return (
264
    <InputNumber
265
      value={value}
266
      onChange={setValue}
267
      onStep={handleStep}
268
      min={0}
269
      max={1000}
270
      step={10}
271
      upHandler={<span>⬆️</span>}
272
      downHandler={<span>⬇️</span>}
273
    />
274
  );
275
}
276
```
277

278
#### Keyboard and Mouse Wheel Configuration
279

280
```typescript
281
// Disable mouse wheel, enable keyboard with custom behavior
282
<InputNumber
283
  defaultValue={50}
284
  wheel={false}
285
  keyboard={true}
286
  onKeyDown={(e) => {
287
    // Ctrl/Cmd + Arrow keys for larger steps
288
    if (e.ctrlKey || e.metaKey) {
289
      e.preventDefault();
290
      // Custom large step handling
291
    }
292
  }}
293
/>
294
```
295

296
#### Integration with Form Libraries
297

298
```typescript
299
// Example with React Hook Form
300
import { Controller, useForm } from "react-hook-form";
301

302
function FormExample() {
303
  const { control, handleSubmit } = useForm();
304
  
305
  return (
306
    <form onSubmit={handleSubmit((data) => console.log(data))}>
307
      <Controller
308
        name="quantity"
309
        control={control}
310
        defaultValue={1}
311
        rules={{
312
          required: "Quantity is required",
313
          min: { value: 1, message: "Minimum quantity is 1" },
314
          max: { value: 100, message: "Maximum quantity is 100" }
315
        }}
316
        render={({ field }) => (
317
          <InputNumber
318
            {...field}
319
            min={1}
320
            max={100}
321
            step={1}
322
            placeholder="Enter quantity"
323
          />
324
        )}
325
      />
326
    </form>
327
  );
328
}
329
```
330

331
## Keyboard Navigation
332

333
RC Input Number provides comprehensive keyboard support for value manipulation:
334

335
- **↑/↓ Arrow Keys**: Increase/decrease value by `step` amount
336
- **Shift + ↑/↓**: Change value by `10 * step` (large increments)
337
- **Ctrl/⌘ + ↑/↓**: Change value by `0.1 * step` (small increments)
338
- **Enter**: Triggers `onPressEnter` callback and validates current input
339
- **Tab**: Standard navigation behavior
340

341
## Mouse Wheel Support
342

343
When `wheel` prop is enabled (default: true):
344

345
- **Scroll Up/Down**: Increase/decrease value by `step` amount
346
- **Shift + Scroll**: Change value by `10 * step` (large increments)
347

348
## Key Features
349

350
1. **Numeric Value Control**: Precise numeric input with validation and constraints
351
2. **Step Controls**: Built-in increment/decrement buttons with customizable appearance
352
3. **Keyboard Navigation**: Arrow keys support with Ctrl/Cmd modifiers for larger steps
353
4. **Mouse Wheel Support**: Optional value adjustment via scroll wheel
354
5. **Custom Formatting**: Flexible value display formatting with parser integration
355
6. **TypeScript Support**: Full type definitions with generic value type support
356
7. **Controlled/Uncontrolled**: Supports both usage patterns seamlessly
357
8. **Accessibility**: ARIA support and keyboard navigation compliance
358
9. **Validation**: Min/max constraints with precision control
359
10. **Customization**: Extensive styling options and custom handler support