Registry / web-framework / react-number-format

react-number-format

library5.4.5jsnpmunverified

react-number-format is a React component library designed for formatting numeric and pattern-based input fields, as well as displaying formatted text. It provides functionalities for adding prefixes, suffixes, and thousands separators, alongside comprehensive input masking capabilities for various patterns like credit card numbers or phone numbers. The library is currently stable at version 5.4.5 and is actively maintained with frequent bug fix releases, supporting a wide range of React versions up to 19. Its key differentiators include a sophisticated caret engine that handles complex formatting scenarios, custom pattern formatting, and the ability to define custom formatting handlers, offering a high degree of customization for user input experiences. The project emphasizes robust handling of user input while ensuring display consistency.

web-framework

npm install react-number-format

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-NUMBER-FORMA

react-number-format

web-frameworkjavascriptv5.4.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NumericFormat

✓ import { NumericFormat } from 'react-number-format';

✗ const NumericFormat = require('react-number-format').NumericFormat;

Use named import for ESM. CommonJS require is generally discouraged for modern React applications.

PatternFormat

✓ import { PatternFormat } from 'react-number-format';

✗ const PatternFormat = require('react-number-format').PatternFormat;

Use named import for ESM. CommonJS require is generally discouraged for modern React applications.

NumberFormatBase

✓ import { NumberFormatBase } from 'react-number-format';

✗ import NumberFormatBase from 'react-number-format';

This is a base component for custom formatting; ensure you use a named import, not a default import.

This quickstart demonstrates how to use `NumericFormat` for currency input with thousands separators and decimal precision, and `PatternFormat` for a phone number mask, showing how to manage their values with React state.

import React, { useState } from 'react'; import { NumericFormat, PatternFormat } from 'react-number-format'; function MyFormattedInputs() { const [numericValue, setNumericValue] = useState(''); const [phoneValue, setPhoneValue] = useState(''); return ( <div> <h2>Numeric Input (Currency)</h2> <NumericFormat value={numericValue} onValueChange={(values) => { setNumericValue(values.value); }} thousandSeparator={true} prefix={'$'} decimalScale={2} fixedDecimalScale placeholder="Enter amount" /> <h2>Phone Number Input</h2> <PatternFormat value={phoneValue} onValueChange={(values) => { setPhoneValue(values.value); }} format="(###) ###-####" mask="_" placeholder="(123) 456-7890" /> <p>Current Numeric Value: {numericValue}</p> <p>Current Phone Value: {phoneValue}</p> </div> ); } export default MyFormattedInputs;

Debug

Known issues

breakingMajor breaking changes occurred when migrating from v4 to v5. Many props were renamed or removed, and the primary components (e.g., `NumberFormat`) were split into `NumericFormat` and `PatternFormat`. Review the official migration guide.

fix

Consult the official v4 to v5 migration guide at `https://s-yadav.github.io/react-number-format/docs/migration` and update your component props and imports accordingly.

affects: >=5.0.0

breakingThe `isCharacterSame` prop was removed from `NumericFormat` and `PatternFormat` (it remains on `NumberFormatBase` for internal use only). Direct usage of this prop on these components will result in an error or undefined behavior.

fix

Remove any direct usage of the `isCharacterSame` prop from `NumericFormat` and `PatternFormat` components. If similar functionality is needed for custom solutions, explore `NumberFormatBase` or alternative approaches.

affects: >=5.4.1

gotchaFrequent bug reports and fixes around caret positioning, especially with complex formatting, custom separators, or specific input sequences. While many fixes are applied in patch releases, unusual interactions might still occur.

fix

Ensure you are on the latest patch version of `react-number-format`. If issues persist, test with simplified configurations and consider opening an issue on the GitHub repository with a minimal reproduction.

affects: >=5.0.0

Errors

Common errors & fixes

Error: Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate.

Often occurs when `onValueChange` handler triggers a state update that causes a re-render, and the component's internal logic re-triggers `onValueChange` in a loop, or when `valueIsNumericString` is not provided correctly.

fix

For versions prior to v5.3.1, this could be related to `valueIsNumericString` not being provided when `values.value` is used. Ensure your `onValueChange` callback manages state correctly without causing infinite loops. Check for strict equality in dependency arrays for `useEffect` if used.

Uncaught ReferenceError: require is not defined

Attempting to use CommonJS `require()` syntax in an ECMAScript Module (ESM) environment (e.g., modern Create React App, Vite, or Node.js with type: 'module').

fix

Change `const { Name } = require('react-number-format');` to `import { Name } from 'react-number-format';`.

defaultValue not triggering onValueChange

Prior to v5.4.5, using `defaultValue` prop might not consistently trigger the `onValueChange` callback upon initial render or certain interactions.

fix

Upgrade to `react-number-format` version `5.4.5` or newer. If you need to programmatically set the initial value and ensure `onValueChange` fires, use the `value` prop with `useState` and manually set the initial state.

Upgrade

Version history

5.4.5latest on npm

Audit

Dependencies

reactrequiredPeer dependency required for any React application.

react-domrequiredPeer dependency required for rendering React components.

Agent activity

8 hits · last 30 days

node

Resources

githubhttps://github.com/s-yadav/react-number-format ↗

packagehttps://www.npmjs.com/package/react-number-format ↗

homepagehttps://s-yadav.github.io/react-number-format/docs/intro ↗