0
# React Number Format
1

2
React Number Format is a sophisticated React component library for formatting numbers in input fields and text display. It provides two main components (NumericFormat and PatternFormat) with a lightweight caret engine that ensures users can only enter text meeting specific numeric or string patterns while providing real-time formatting for display.
3

4
## Package Information
5

6
- **Package Name**: react-number-format
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-number-format` or `yarn add react-number-format`
10

11
## Core Imports
12

13
```typescript
14
import { NumericFormat, PatternFormat, NumberFormatBase } from "react-number-format";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { NumericFormat, PatternFormat, NumberFormatBase } = require("react-number-format");
21
```
22

23
Import specific utilities:
24

25
```typescript
26
import { 
27
  numericFormatter, 
28
  removeNumericFormat, 
29
  patternFormatter, 
30
  removePatternFormat,
31
  useNumericFormat,
32
  usePatternFormat
33
} from "react-number-format";
34
```
35

36
## Basic Usage
37

38
### NumericFormat Component
39

40
```typescript
41
import React from "react";
42
import { NumericFormat } from "react-number-format";
43

44
function CurrencyInput() {
45
  return (
46
    <NumericFormat
47
      value={1234.56}
48
      displayType="input"
49
      thousandSeparator={true}
50
      prefix="$"
51
      decimalScale={2}
52
      fixedDecimalScale={true}
53
      onValueChange={(values) => {
54
        console.log(values.floatValue); // 1234.56
55
        console.log(values.formattedValue); // $1,234.56
56
      }}
57
    />
58
  );
59
}
60
```
61

62
### PatternFormat Component
63

64
```typescript
65
import React from "react";
66
import { PatternFormat } from "react-number-format";
67

68
function PhoneInput() {
69
  return (
70
    <PatternFormat
71
      format="(###) ###-####"
72
      allowEmptyFormatting
73
      mask="_"
74
      onValueChange={(values) => {
75
        console.log(values.value); // 1234567890
76
        console.log(values.formattedValue); // (123) 456-7890
77
      }}
78
    />
79
  );
80
}
81
```
82

83
## Architecture
84

85
React Number Format is built around several key components:
86

87
- **NumberFormatBase**: Core component providing base formatting functionality with customizable format/removeFormatting functions
88
- **NumericFormat**: Specialized component for numeric input with prefix, suffix, thousands separators, and decimal handling
89
- **PatternFormat**: Specialized component for custom string pattern formatting with input masking capabilities
90
- **Utility Functions**: Standalone formatting functions for use without React components
91
- **React Hooks**: useNumericFormat and usePatternFormat hooks for custom implementations
92
- **Caret Engine**: Sophisticated caret positioning system ensuring proper cursor behavior during formatting
93

94
## Capabilities
95

96
### Numeric Formatting
97

98
Handles numeric input formatting with prefix, suffix, thousands separators, decimal scale control, and international number formatting styles.
99

100
```typescript { .api }
101
function NumericFormat<BaseType = InputAttributes>(
102
  props: NumericFormatProps<BaseType>
103
): React.ReactElement;
104

105
interface NumericFormatProps<BaseType = InputAttributes> {
106
  thousandSeparator?: boolean | string;
107
  decimalSeparator?: string;
108
  allowedDecimalSeparators?: Array<string>;
109
  thousandsGroupStyle?: 'thousand' | 'lakh' | 'wan' | 'none';
110
  decimalScale?: number;
111
  fixedDecimalScale?: boolean;
112
  allowNegative?: boolean;
113
  allowLeadingZeros?: boolean;
114
  suffix?: string;
115
  prefix?: string;
116
}
117
```
118

119
[Numeric Formatting](./numeric-formatting.md)
120

121
### Pattern Formatting
122

123
Provides custom string pattern formatting with input masking for phone numbers, credit cards, dates, and other structured text formats.
124

125
```typescript { .api }
126
function PatternFormat<BaseType = InputAttributes>(
127
  props: PatternFormatProps<BaseType>
128
): React.ReactElement;
129

130
interface PatternFormatProps<BaseType = InputAttributes> {
131
  format: string;
132
  mask?: string | string[];
133
  allowEmptyFormatting?: boolean;
134
  patternChar?: string;
135
}
136
```
137

138
[Pattern Formatting](./pattern-formatting.md)
139

140
### Base Component System
141

142
Core component providing customizable formatting functionality that both NumericFormat and PatternFormat extend.
143

144
```typescript { .api }
145
function NumberFormatBase<BaseType = InputAttributes>(
146
  props: NumberFormatBaseProps<BaseType>
147
): React.ReactElement;
148

149
interface NumberFormatBaseProps<BaseType = InputAttributes> {
150
  type?: 'text' | 'tel' | 'password';
151
  displayType?: 'input' | 'text';
152
  customInput?: React.ComponentType<BaseType>;
153
  renderText?: (formattedValue: string, otherProps: Partial<NumberFormatBaseProps>) => React.ReactNode;
154
  format?: (inputValue: string) => string;
155
  removeFormatting?: (inputValue: string, changeMeta?: ChangeMeta) => string;
156
  getInputRef?: ((el: HTMLInputElement) => void) | React.Ref<any>;
157
  value?: number | string | null;
158
  defaultValue?: number | string | null;
159
  valueIsNumericString?: boolean;
160
  onValueChange?: OnValueChange;
161
  isAllowed?: (values: NumberFormatValues) => boolean;
162
  getCaretBoundary?: (formattedValue: string) => boolean[];
163
  isValidInputCharacter?: (character: string) => boolean;
164
  isCharacterSame?: IsCharacterSame;
165
}
166
```
167

168
[Base Component System](./base-component.md)
169

170
### Utility Functions
171

172
Standalone formatting functions that can be used independently of React components for server-side processing, validation, or custom implementations.
173

174
```typescript { .api }
175
// Numeric formatting utilities
176
function numericFormatter<BaseType = InputAttributes>(
177
  numStr: string,
178
  props: NumericFormatProps<BaseType>
179
): string;
180

181
function removeNumericFormat<BaseType = InputAttributes>(
182
  value: string,
183
  changeMeta: ChangeMeta,
184
  props: NumericFormatProps<BaseType>
185
): string;
186

187
// Pattern formatting utilities  
188
function patternFormatter<BaseType = InputAttributes>(
189
  numStr: string,
190
  props: PatternFormatProps<BaseType>
191
): string;
192

193
function removePatternFormat<BaseType = InputAttributes>(
194
  value: string,
195
  changeMeta: ChangeMeta,
196
  props: PatternFormatProps<BaseType>
197
): string;
198
```
199

200
[Utility Functions](./utility-functions.md)
201

202
### React Hooks
203

204
React hooks for advanced use cases where you need to integrate formatting logic with custom components or complex state management.
205

206
```typescript { .api }
207
function useNumericFormat<BaseType = InputAttributes>(
208
  props: NumericFormatProps<BaseType>
209
): NumberFormatBaseProps<BaseType>;
210

211
function usePatternFormat<BaseType = InputAttributes>(
212
  props: PatternFormatProps<BaseType>
213
): NumberFormatBaseProps<BaseType>;
214
```
215

216
[React Hooks](./react-hooks.md)
217

218
## Core Types
219

220
```typescript { .api }
221
interface NumberFormatValues {
222
  floatValue: number | undefined;
223
  formattedValue: string;
224
  value: string;
225
}
226

227
interface SourceInfo {
228
  event?: React.SyntheticEvent<HTMLInputElement>;
229
  source: SourceType;
230
}
231

232
interface ChangeMeta {
233
  from: { start: number; end: number };
234
  to: { start: number; end: number };
235
  lastValue: string;
236
}
237

238
type OnValueChange = (values: NumberFormatValues, sourceInfo: SourceInfo) => void;
239

240
enum SourceType {
241
  event = 'event',
242
  props = 'prop'
243
}
244

245
type InputAttributes = Omit<
246
  React.InputHTMLAttributes<HTMLInputElement>,
247
  'defaultValue' | 'value' | 'children'
248
>;
249

250
type FormatInputValueFunction = (inputValue: string) => string;
251
type RemoveFormattingFunction = (inputValue: string, changeMeta?: ChangeMeta) => string;
252

253
type IsCharacterSame = (compareProps: {
254
  currentValue: string;
255
  lastValue: string;
256
  formattedValue: string;
257
  currentValueIndex: number;
258
  formattedValueIndex: number;
259
}) => boolean;
260
```