0
# Numeric Formatting
1

2
Comprehensive numeric input formatting with prefix, suffix, thousands separators, decimal scale control, and international number formatting styles. Perfect for currency inputs, financial data, percentages, and any scenario requiring controlled numeric input.
3

4
## Capabilities
5

6
### NumericFormat Component
7

8
React component that provides sophisticated numeric input formatting with full control over display options, validation, and user input handling.
9

10
```typescript { .api }
11
/**
12
 * NumericFormat component for formatting numeric input values
13
 * @param props - Configuration options for numeric formatting
14
 * @returns React element with formatted numeric input
15
 */
16
function NumericFormat<BaseType = InputAttributes>(
17
  props: NumericFormatProps<BaseType>
18
): React.ReactElement;
19

20
interface NumericFormatProps<BaseType = InputAttributes> {
21
  /** Enable thousands separator. Boolean true uses comma, string specifies custom separator */
22
  thousandSeparator?: boolean | string;
23
  /** Character used for decimal separation. Default is '.' */
24
  decimalSeparator?: string;
25
  /** Array of characters that can be used as decimal separators in input */
26
  allowedDecimalSeparators?: Array<string>;
27
  /** Style for thousands grouping: 'thousand' (default), 'lakh', 'wan', or 'none' */
28
  thousandsGroupStyle?: 'thousand' | 'lakh' | 'wan' | 'none';
29
  /** Maximum number of digits after decimal separator */
30
  decimalScale?: number;
31
  /** Whether to always show decimal places even if zero */
32
  fixedDecimalScale?: boolean;
33
  /** Whether to allow negative numbers */
34
  allowNegative?: boolean;
35
  /** Whether to allow leading zeros in integer part */
36
  allowLeadingZeros?: boolean;
37
  /** String to display after the formatted number */
38
  suffix?: string;
39
  /** String to display before the formatted number */
40
  prefix?: string;
41
}
42
```
43

44
**Usage Examples:**
45

46
```typescript
47
import React from "react";
48
import { NumericFormat } from "react-number-format";
49

50
// Currency formatting
51
function CurrencyInput({ value, onChange }) {
52
  return (
53
    <NumericFormat
54
      value={value}
55
      onValueChange={(values) => onChange(values.floatValue)}
56
      thousandSeparator={true}
57
      prefix="$"
58
      decimalScale={2}
59
      fixedDecimalScale={true}
60
      placeholder="$0.00"
61
    />
62
  );
63
}
64

65
// Percentage formatting
66
function PercentageInput({ value, onChange }) {
67
  return (
68
    <NumericFormat
69
      value={value}
70
      onValueChange={(values) => onChange(values.floatValue)}
71
      suffix="%"
72
      decimalScale={2}
73
      allowNegative={false}
74
      placeholder="0.00%"
75
    />
76
  );
77
}
78

79
// International formatting (Indian lakh system)
80
function LakhInput({ value, onChange }) {
81
  return (
82
    <NumericFormat
83
      value={value}
84
      onValueChange={(values) => onChange(values.floatValue)}
85
      thousandSeparator={true}
86
      thousandsGroupStyle="lakh"
87
      prefix="₹"
88
      placeholder="₹0"
89
    />
90
  );
91
}
92

93
// Custom separator and validation
94
function CustomNumericInput({ value, onChange }) {
95
  return (
96
    <NumericFormat
97
      value={value}
98
      onValueChange={(values) => onChange(values.floatValue)}
99
      thousandSeparator=" "
100
      decimalSeparator=","
101
      allowedDecimalSeparators={[",", "."]}
102
      decimalScale={3}
103
      isAllowed={(values) => {
104
        const { floatValue } = values;
105
        return floatValue === undefined || (floatValue >= 0 && floatValue <= 1000000);
106
      }}
107
    />
108
  );
109
}
110
```
111

112
### Numeric Formatter Function
113

114
Standalone formatting function for converting numeric strings to formatted display strings without React components.
115

116
```typescript { .api }
117
/**
118
 * Format a numeric string according to NumericFormat props
119
 * @param numStr - The numeric string to format
120
 * @param props - Formatting configuration options
121
 * @returns Formatted string ready for display
122
 */
123
function numericFormatter<BaseType = InputAttributes>(
124
  numStr: string,
125
  props: NumericFormatProps<BaseType>
126
): string;
127
```
128

129
**Usage Examples:**
130

131
```typescript
132
import { numericFormatter } from "react-number-format";
133

134
// Format currency on server or in utilities
135
const formatCurrency = (amount: number) => {
136
  return numericFormatter(amount.toString(), {
137
    thousandSeparator: true,
138
    prefix: "$",
139
    decimalScale: 2,
140
    fixedDecimalScale: true,
141
  });
142
};
143

144
console.log(formatCurrency(1234.5)); // "$1,234.50"
145

146
// Format percentages
147
const formatPercentage = (value: number) => {
148
  return numericFormatter((value * 100).toString(), {
149
    suffix: "%",
150
    decimalScale: 1,
151
    fixedDecimalScale: true,
152
  });
153
};
154

155
console.log(formatPercentage(0.156)); // "15.6%"
156
```
157

158
### Remove Numeric Formatting
159

160
Function to extract the raw numeric value from formatted strings, handling all formatting elements like separators and prefixes.
161

162
```typescript { .api }
163
/**
164
 * Remove formatting from a numeric string to get raw numeric value
165
 * @param value - The formatted string to parse
166
 * @param changeMeta - Metadata about the change (for cursor positioning)
167
 * @param props - The formatting configuration that was applied
168
 * @returns Raw numeric string without formatting
169
 */
170
function removeNumericFormat<BaseType = InputAttributes>(
171
  value: string,
172
  changeMeta: ChangeMeta,
173
  props: NumericFormatProps<BaseType>
174
): string;
175
```
176

177
**Usage Examples:**
178

179
```typescript
180
import { removeNumericFormat } from "react-number-format";
181

182
// Parse currency values
183
const parseCurrency = (formattedValue: string) => {
184
  const rawValue = removeNumericFormat(formattedValue, undefined, {
185
    thousandSeparator: true,
186
    prefix: "$",
187
    decimalScale: 2,
188
  });
189
  return parseFloat(rawValue) || 0;
190
};
191

192
console.log(parseCurrency("$1,234.56")); // 1234.56
193

194
// Parse percentage values
195
const parsePercentage = (formattedValue: string) => {
196
  const rawValue = removeNumericFormat(formattedValue, undefined, {
197
    suffix: "%",
198
    decimalScale: 2,
199
  });
200
  return (parseFloat(rawValue) || 0) / 100;
201
};
202

203
console.log(parsePercentage("15.6%")); // 0.156
204
```
205

206
### Get Numeric Caret Boundary
207

208
Function that determines valid caret positions within formatted numeric strings, ensuring the cursor can only be placed at appropriate locations.
209

210
```typescript { .api }
211
/**
212
 * Get array of valid caret positions for formatted numeric value
213
 * @param formattedValue - The formatted numeric string
214
 * @param props - The formatting configuration
215
 * @returns Array of booleans indicating valid caret positions
216
 */
217
function getNumericCaretBoundary<BaseType = InputAttributes>(
218
  formattedValue: string,
219
  props: NumericFormatProps<BaseType>
220
): boolean[];
221
```
222

223
### Use Numeric Format Hook
224

225
React hook that converts NumericFormat props into NumberFormatBase props, useful for building custom components that need numeric formatting behavior.
226

227
```typescript { .api }
228
/**
229
 * Hook that provides numeric formatting logic for custom components
230
 * @param props - NumericFormat configuration
231
 * @returns Props ready for NumberFormatBase component
232
 */
233
function useNumericFormat<BaseType = InputAttributes>(
234
  props: NumericFormatProps<BaseType>
235
): NumberFormatBaseProps<BaseType>;
236
```
237

238
**Usage Examples:**
239

240
```typescript
241
import React from "react";
242
import { useNumericFormat, NumberFormatBase } from "react-number-format";
243

244
// Custom currency input with additional styling
245
function CustomCurrencyInput({ value, onChange, className }) {
246
  const numericFormatProps = useNumericFormat({
247
    value,
248
    onValueChange: onChange,
249
    thousandSeparator: true,
250
    prefix: "$",
251
    decimalScale: 2,
252
    fixedDecimalScale: true,
253
  });
254

255
  return (
256
    <div className={`currency-wrapper ${className}`}>
257
      <NumberFormatBase
258
        {...numericFormatProps}
259
        customInput={(props) => (
260
          <input {...props} className="currency-input" />
261
        )}
262
      />
263
    </div>
264
  );
265
}
266
```
267

268
## International Number Formatting
269

270
### Thousands Group Styles
271

272
Different cultural conventions for number grouping:
273

274
- **thousand**: 1,234,567.89 (Western style)
275
- **lakh**: 12,34,567.89 (Indian numbering system)
276
- **wan**: 123,4567.89 (Chinese/Japanese numbering system)
277
- **none**: 1234567.89 (No thousands separator)
278

279
```typescript
280
// Indian lakh/crore system
281
<NumericFormat 
282
  thousandsGroupStyle="lakh" 
283
  thousandSeparator={true}
284
  value={1234567}
285
/> // Displays: 12,34,567
286

287
// Chinese wan system  
288
<NumericFormat
289
  thousandsGroupStyle="wan"
290
  thousandSeparator={true}
291
  value={1234567}
292
/> // Displays: 123,4567
293
```
294

295
### Custom Separators
296

297
Support for different decimal and thousands separators used internationally:
298

299
```typescript
300
// European formatting (space for thousands, comma for decimal)
301
<NumericFormat
302
  thousandSeparator=" "
303
  decimalSeparator=","
304
  value={1234.56}
305
/> // Displays: 1 234,56
306

307
// Multiple allowed decimal separators for user input
308
<NumericFormat
309
  decimalSeparator=","
310
  allowedDecimalSeparators={[",", "."]}
311
  value={1234.56}
312
/> // Users can type either "," or "." for decimal
313
```