react-financial-input

A React currency input that formats as you type, with h/k/m/b multiplier shortcuts designed for modern desktop and mobile browsers.

Zero runtime dependencies. Unstyled by default.

Open the playground in StackBlitz → · Browse every state in Storybook → · Framework examples →

Quick start

npm install react-financial-input

import { useState } from 'react';
import { FinancialInput } from 'react-financial-input';

export const AmountField = () => {
  const [amount, setAmount] = useState<number | null>(null);

  return (
    <>
      <label htmlFor="amount">Amount</label>
      <FinancialInput id="amount" value={amount} onChange={setAmount} />
    </>
  );
};

Type 1234567 and you get 1,234,567; type 2.5m and you get 2,500,000. onChange gives you a number, or null while the value is incomplete — never NaN. Want strings instead? valueType="string".

Want it styled? One import, opt-in:

import 'react-financial-input/styles.css';

Showing currency flags? Windows has no flag glyphs of its own, so the font ships too. Importing it is what makes flags work on every OS, at 80 kB:

import 'react-financial-input/flags.css';

React 18 or newer (>=18.0.0). Nothing else.

Submitting a native <form>? Do not put name on the input — it submits the formatted "1,234.56". Use a hidden field.

What it does

Typing

Digits group as you type
2.5m expands to millions

Editing

Backspace across a separator
Paste is sanitised, not refused
Undo, one step per edit

Currency

Symbol and separators from Intl
Search, for when 162 is the list

locale and currency come from Intl, and the symbol follows the locale, not the currency — SEK reads SEK in en-US and kr only in sv-SE.

Grouping follows the locale too, including the Indian lakh/crore system: en-IN gives 1,23,45,67,890, not 1,234,567,890.

Feedback and extras

Refused keystrokes flash
Clear button, undoable
Multiplier keys for a numeric keypad

All of these are off by default — the component renders a bare <input>, and the hook gives you the behaviour to render yourself. See the extras.

Why this one

Most currency inputs ask for a numeric keypad, which has no letter keys — so 2.5m cannot be typed on a phone at all. This one reads InputEvent.inputType rather than guessing from key codes, so paste, drag-drop, cut, word delete and Android IME composition each have a case rather than a shrug.

The design notes have the reasoning, the input event cheatsheet and the device support matrix.

Props

Every native <input> prop is passed through and ref is forwarded, except four: value, defaultValue and onChange carry the number or the canonical string rather than DOM strings, and onError is the refused-keystroke callback, not the DOM's. type is always text.

Prop	Type	Default	Description
value	number | string | null	undefined	Typed by valueType. A string may be canonical, display, or 2.5m.
onChange	(value: number | string | null) => void	—	The number, or canonical text — never the formatted string.
valueType	'number' | 'string'	'number'	Which of the two value and onChange speak.
onError	() => void	—	Called when a keystroke is refused.
options.scale	number	2	Maximum decimal places. 0 refuses the decimal point.
options.maxDigits	number	11	Maximum integer digits.
options.locale	string	—	BCP 47 tag. Supplies separators and the currency symbol.
options.currency	string	—	ISO 4217 code. The symbol is returned, not put in the value.
options.groupSeparator	string	','	Overrides the locale.
options.decimalSeparator	string	'.'	Overrides the locale.
options.shortcuts	Record<string, number>	h/k/m/b	Characters to multipliers. Must be powers of ten.
options.range	'ALL' | 'POSITIVE'	'ALL'	'POSITIVE' refuses negatives.
options.inputMode	'text' | 'decimal' | 'numeric'	'text'	Which keyboard mobile raises.
options.flashOnError	boolean	true	Flash on a refused keystroke. Colour only; add rfi-input--shake for motion.

Shortcuts

Key	Multiplier
h	×100
k	×1,000
m	×1,000,000
b	×1,000,000,000

Typing one on its own reads as one of that unit, so k gives 1,000. Override with options.shortcuts.

Headless

Keep the formatting and validation, bring your own input:

import { useFinancialInput } from 'react-financial-input';

const { getInputProps } = useFinancialInput({ value, onChange: setValue });

<TextField slotProps={{ htmlInput: getInputProps() }} />; // MUI
<Input {...getInputProps()} />; // Chakra

The hook returns everything the extras are built from:

Returned	For
getInputProps()	Spread onto any input
applyShortcut(character)	Multiplier tap targets
clear()	A clear button. Undoable, like any other edit
symbol, symbolPosition	The currency symbol and which side it belongs on
numericValue, displayValue	The committed number, and what is on screen
canonicalValue	The string to send onward — no grouping, . fraction

Without React

parseAmount('$1,234.56 USD') gives 1234.56, and parseAmount('2.5m') gives 2500000 — the same rules the input applies to a paste, as one call, with no DOM. Currency lists, search and flag emoji come from Intl rather than a bundled table.

All of it is in UTILS.md.

Docs

• EXAMPLES.md — Next.js, React Hook Form, Formik, MUI, Chakra, TanStack Form, plain forms, and how to test it.
• UTILS.md — the non-React exports: parsing, formatting, currency lists, search, flags.
• DESIGN.md — why it behaves as it does: the state model and controlled mode, the mobile keyboard trade-off, exact multipliers, the input event cheatsheet, the device support matrix, styling — and what it does not do: numbers above 2^53, and the rows nobody has tested on real hardware.
• CONTRIBUTING.md — architecture rules and local setup.
• CI.md — what each workflow does, and how to publish.
• HISTORY.md — where it came from, why it stalled for two years, and what real devices taught it.

License

MIT