# react-number-format: controlled numeric and pattern inputs for React

> react-number-format is an MIT-licensed React component that formats numbers in an input or as plain text, with a caret engine that lets users type only what the pattern allows. It fits currency fields and phone masks, and is the wrong tool when you need a full form state library or native mobile input control.

**s-yadav/react-number-format** — React component to format numbers in an input or as a text.

- Repository: https://github.com/s-yadav/react-number-format
- Stars: 4,100 · Forks: 415
- Language: JavaScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/s-yadav-react-number-format

## The input problem react-number-format was built to solve

A plain `<input type="text">` accepts anything. A plain `<input type="number">` accepts digits but gives you little control over grouping, prefixes, suffixes, or the caret position while the user types. Building a currency field by hand means intercepting every keystroke, deciding whether the new string is valid, reformatting it, and then putting the caret back where the user expects. That last step is where most hand-rolled implementations break: the user types a digit in the middle of a grouped number and the cursor jumps to the end.

The README describes the project as an input-formatter library with a sophisticated and light weight caret engine, and states that it ensures a user can only enter text that meets specific numeric or string patterns while formatting the input value for display. That is the whole scope. It is a component, not a form framework. The audience is React developers who need a controlled field for money, quantities, percentages, or structured strings such as phone numbers, and who want the formatting rules to live in props rather than in a custom keydown handler.

## NumericFormat, PatternFormat and the caret engine

The package exposes two components. `NumericFormat` handles numbers with prefix, suffix, thousands separator, and decimal behaviour. `PatternFormat` handles string masks such as phone numbers, where the shape is fixed and the characters are not necessarily numeric. Both are imported from the same entry point.

The caret engine is the part that distinguishes this from a formatting function applied on blur. Because the component owns the input, it can reformat on each change and still place the selection correctly, so editing the middle of a value does not move the cursor to the end. The README also lists a custom formatting handler and custom pattern formatting, which means the built-in grouping and mask rules are not the only option: you can supply your own logic when the default output does not match what you need.

Formatting as text is a separate mode. The README lists format number in an input or format as a simple text as a feature, so the same rules can render a display string outside an input, which is useful when a table cell and an editable field must agree on how a value looks.

## Installing react-number-format and formatting a first value

The README gives two package managers. Either command installs the package under the name `react-number-format`.

```bash
npm install react-number-format
```

```bash
yarn add react-number-format
```

After installing, import the component you need. The README shows a named import for each one.

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

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

A first real use is a currency field. The README points to the NumericFormat props page for the full list, and the documented features include prefix, suffix and thousands separator, so a field that shows grouped digits and a currency symbol is within the intended scope. The component is controlled, so you hold the value in state and pass it back in. What you should see in the browser is a field that groups digits as you type and keeps the caret where you left it, rather than jumping to the end of the string.

For a fixed-shape string, `PatternFormat` takes a mask instead of grouping rules. The README's feature list calls this input masking, and the phone number case is the usual example. Both components accept a custom formatting handler when the built-in rules are not enough.

## Where react-number-format stops being the right tool

The README does not document rollback behaviour, and it does not describe what happens when a pasted string cannot be reconciled with the current pattern. Paste is the common failure path for any masked input: the user copies a value with spaces, parentheses, or a country code, and the component has to decide which characters survive. Because the caret engine is described as enforcing what a user can enter, the behaviour on rejected input is a design decision you should test against your own data rather than assume.

It is also not a form library. It does not manage validation messages, submission, or cross-field rules, and the README makes no claim in that direction. If you need those, this component sits inside that system rather than replacing it.

React Native is a separate case. The README and the repository layout describe a web component built on React DOM inputs; the example directory is a webpack dev server setup. There is no React Native entry point in the README, so a mobile app that needs a native numeric keyboard is outside what this package documents.

## How it compares with a general formatting library

The obvious alternative is a general-purpose number formatting library such as Intl.NumberFormat, which is built into the JavaScript runtime and needs no dependency. The difference is in where the work happens. Intl.NumberFormat takes a number and returns a string. It has no opinion about an input element, no caret handling, and no concept of a partially typed value. You would still have to write the change handler and the selection logic yourself, which is the part react-number-format exists to remove.

The trade-off runs the other way too. A formatting function is trivial to test, has no React version constraints, and adds nothing to your bundle. react-number-format is a component with a peer relationship to React, and the release history shows that relationship needs attention: v5.4.3 is labelled Support React 19, which means React version compatibility is something the maintainer tracks release by release. If your application only needs to render formatted strings and never needs an editable masked field, the built-in formatter is the smaller answer.

## Maintenance, licensing and the cost of upgrading

The package is MIT licensed, and the package.json declares the same. For most applications that means you can use it commercially and modify it, provided you keep the licence and copyright notice with the distributed code. That is a summary of the licence identifier, not legal advice; read the LICENSE file in the repository if the terms matter to your organisation.

The last push to the default branch was on 2026-03-22, the same day as the v5.4.5 bug fix release. Before that, v5.4.4 landed on 2025-04-12 and v5.4.3, which added React 19 support, on 2024-12-25. The gap between v5.4.4 and v5.4.5 is roughly eleven months, so releases arrive when there is something to fix rather than on a schedule. Plan for that: if a bug affects you, the fix may wait.

The upgrade cost is concentrated in the v4 to v5 transition. The README links a dedicated migration page, which is a signal that the API changed enough to need one. If you are on v4, read that page before upgrading rather than treating it as a patch bump. The package publishes both a CommonJS and an ES module build, and marks itself side-effect free, so bundlers can tree-shake it.

## Which React apps should take this dependency

Take it when you have a controlled field whose displayed value differs from the stored value: a currency amount held as a number and shown with grouping and a symbol, a quantity with a suffix, or a phone number stored as digits and shown with a mask. The caret engine is the reason to prefer it over a formatter plus a hand-written handler, because the caret handling is the part that is tedious to get right and easy to get subtly wrong.

Skip it when the value is never edited. A read-only table of formatted numbers does not need a component; the platform formatter handles that with no dependency and no React version constraint. Skip it as well if you need validation, submission, and error state in one place, because that is a different category of library and this one does not claim to be it. If you are building for React Native, the README describes a web component and nothing else.

Before adopting, check the React version your application runs against the release you install, since React 19 support arrived in a specific release rather than being assumed. Then test paste behaviour with the real strings your users will paste, because the README does not document how rejected characters are handled.

## Conclusion

Adopt react-number-format if you need a controlled React input that enforces a numeric or string pattern and renders formatted output, and you are willing to manage value and caret behaviour yourself. Do not adopt it as a replacement for a form state library or for React Native, which the README does not cover. Verify first that your React version matches the one supported by the release you install, and read the v4 to v5 migration page if you are upgrading an existing codebase.

## FAQ

### How do I install react-number-format?

The README gives two commands: `npm install react-number-format` or `yarn add react-number-format`. Both install the package under that name.

### What is react-number-format an alternative to?

The README does not name a competing library. The closest comparison in the README is the built-in Intl.NumberFormat, which formats a number into a string but has no input element and no caret handling, so you would still write the change handler yourself.

### What is an example of a number format in react-number-format?

The README lists prefix, suffix and thousands separator, input masking, and custom pattern formatting as features. A currency field with grouped digits and a symbol, or a masked phone number via PatternFormat, are the documented use cases.

## Sources

- [Issues](https://github.com/s-yadav/react-number-format/issues)
- [License: MIT](https://github.com/s-yadav/react-number-format/blob/master/LICENSE)
- [README](https://github.com/s-yadav/react-number-format/blob/master/README.md)
- [Releases](https://github.com/s-yadav/react-number-format/releases)
- [s-yadav/react-number-format on GitHub](https://github.com/s-yadav/react-number-format)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/s-yadav-react-number-format