React Number Format

Common errors

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

  cause 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

  cause 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

  cause 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.

Warnings

• breaking Major 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.
• breaking The `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.
• gotcha Frequent 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.

Install

• npm install react-number-format npm
• yarn add react-number-format yarn
• pnpm add react-number-format pnpm

Imports

• NumericFormat
  wrong:

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

  correct:

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

  Use named import for ESM. CommonJS require is generally discouraged for modern React applications.
• PatternFormat
  wrong:

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

  correct:

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

  Use named import for ESM. CommonJS require is generally discouraged for modern React applications.
• NumberFormatBase
  wrong:

  import NumberFormatBase from 'react-number-format';

  correct:

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

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

Quickstart

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;