{"id":11819,"library":"react-number-format","title":"React Number Format","description":"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.","status":"active","version":"5.4.5","language":"javascript","source_language":"en","source_url":"https://github.com/s-yadav/react-number-format","tags":["javascript","react-component","react","currency","input","number","number-format","mask","typescript"],"install":[{"cmd":"npm install react-number-format","lang":"bash","label":"npm"},{"cmd":"yarn add react-number-format","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-number-format","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for any React application.","package":"react","optional":false},{"reason":"Peer dependency required for rendering React components.","package":"react-dom","optional":false}],"imports":[{"note":"Use named import for ESM. CommonJS require is generally discouraged for modern React applications.","wrong":"const NumericFormat = require('react-number-format').NumericFormat;","symbol":"NumericFormat","correct":"import { NumericFormat } from 'react-number-format';"},{"note":"Use named import for ESM. CommonJS require is generally discouraged for modern React applications.","wrong":"const PatternFormat = require('react-number-format').PatternFormat;","symbol":"PatternFormat","correct":"import { PatternFormat } from 'react-number-format';"},{"note":"This is a base component for custom formatting; ensure you use a named import, not a default import.","wrong":"import NumberFormatBase from 'react-number-format';","symbol":"NumberFormatBase","correct":"import { NumberFormatBase } from 'react-number-format';"}],"quickstart":{"code":"import React, { useState } from 'react';\nimport { NumericFormat, PatternFormat } from 'react-number-format';\n\nfunction MyFormattedInputs() {\n  const [numericValue, setNumericValue] = useState('');\n  const [phoneValue, setPhoneValue] = useState('');\n\n  return (\n    <div>\n      <h2>Numeric Input (Currency)</h2>\n      <NumericFormat\n        value={numericValue}\n        onValueChange={(values) => {\n          setNumericValue(values.value);\n        }}\n        thousandSeparator={true}\n        prefix={'$'}\n        decimalScale={2}\n        fixedDecimalScale\n        placeholder=\"Enter amount\"\n      />\n\n      <h2>Phone Number Input</h2>\n      <PatternFormat\n        value={phoneValue}\n        onValueChange={(values) => {\n          setPhoneValue(values.value);\n        }}\n        format=\"(###) ###-####\"\n        mask=\"_\"\n        placeholder=\"(123) 456-7890\"\n      />\n\n      <p>Current Numeric Value: {numericValue}</p>\n      <p>Current Phone Value: {phoneValue}</p>\n    </div>\n  );\n}\n\nexport default MyFormattedInputs;","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=5.4.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"Error: Maximum update depth exceeded. This can happen when a component repeatedly calls setState inside componentWillUpdate or componentDidUpdate."},{"fix":"Change `const { Name } = require('react-number-format');` to `import { Name } from 'react-number-format';`.","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').","error":"Uncaught ReferenceError: require is not defined"},{"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.","cause":"Prior to v5.4.5, using `defaultValue` prop might not consistently trigger the `onValueChange` callback upon initial render or certain interactions.","error":"defaultValue not triggering onValueChange"}],"ecosystem":"npm"}