currency-fomatter

currency-fomatter

The currency toolkit for React — format, parse, and input currencies with zero config.

Unlike other formatting libraries that only give you a component, currency-fomatter gives you 3 layers you can use independently:

Layer	What	Use case
formatCurrency() / parseCurrency()	Standalone functions	Node.js, SSR, any JS — no React needed
useCurrencyInput() / useCurrencyFormat()	React hooks	Headless — bring your own UI
<CurrencyFormat /> / <PatternFormat />	React components	Drop-in input with full formatting

Live Demo

npm install currency-fomatter

Why currency-fomatter?

Feature	currency-fomatter	react-number-format	react-currency-input-field
Standalone utils (no React)	Yes	No	No
Format + Parse symmetry	Yes	No	No
Compact format (1K, 1M, 1B)	Yes	No	No
ISO 4217 currency database	Yes	No	No
Auto locale detection (Intl)	Yes	No	Partial
React hook (headless)	Yes	No	No
IME support (CJK input)	Yes	No	No
Mobile keyboard (inputMode)	Auto	Manual	Manual
Accessibility (ARIA)	Built-in	No	No
Pattern format (phone, card)	Yes	Yes	No
Custom input component	Yes	Yes	Yes
TypeScript	Yes	Yes	Yes
Bundle size	~8KB	~7KB	~10KB

Quick Start

Just format a number (no React)

import { formatCurrency, parseCurrency } from "currency-fomatter";

formatCurrency(1234567.89, { prefix: "$", thousandSeparator: "," });
// → "$1,234,567.89"

parseCurrency("$1,234,567.89", { prefix: "$", thousandSeparator: "," });
// → { value: "1234567.89", floatValue: 1234567.89 }

Auto-config from currency code (ISO 4217)

import { getCurrencyConfig, formatCurrency } from "currency-fomatter";

const usd = getCurrencyConfig("USD"); // { prefix: "$", decimalScale: 2, ... }
const jpy = getCurrencyConfig("JPY"); // { prefix: "¥", decimalScale: 0, ... }
const vnd = getCurrencyConfig("VND"); // { suffix: " ₫", decimalScale: 0, ... }

formatCurrency(1234567, getCurrencyConfig("EUR"));
// → "1,234,567.00 €"

50+ currencies built-in. Unknown currencies fall back to Intl.NumberFormat.

React component

import { CurrencyFormat } from "currency-fomatter";

<CurrencyFormat
  value={1234.56}
  prefix="$"
  thousandSeparator=","
  decimalScale={2}
  fixedDecimalScale
  onValueChange={(values) => {
    console.log(values.floatValue); // 1234.56
  }}
/>

React hook — headless, works with ANY input

import { useCurrencyInput } from "currency-fomatter";

function PriceInput() {
  const { value, formattedValue, getInputProps } = useCurrencyInput({
    currency: "USD",     // Auto-configures $, 2 decimals
    initialValue: 1234.56,
  });

  // Works with plain <input>, Material UI, Chakra, Ant Design — anything
  return <input {...getInputProps()} />;
}

Pattern format (phone, card, date)

import { PatternFormat } from "currency-fomatter";

<PatternFormat format="+1 (###) ###-####" mask="_" />
// → +1 (555) 123-4567

<PatternFormat format="#### #### #### ####" mask="_" />
// → 4111 1111 1111 1111

Standalone Utilities

formatCurrency

import { formatCurrency } from "currency-fomatter";

// Basic
formatCurrency(1234567.89);
// → "1,234,567.89"

// With options
formatCurrency(1234567.89, {
  prefix: "$",
  decimalScale: 2,
  fixedDecimalScale: true,
  thousandSeparator: ",",
});
// → "$1,234,567.89"

// Indian number system
formatCurrency(1234567, { prefix: "₹", thousandSpacing: "2s" });
// → "₹12,34,567"

parseCurrency

Round-trip parsing — the inverse of formatCurrency:

import { parseCurrency } from "currency-fomatter";

parseCurrency("$1,234.56", { prefix: "$", thousandSeparator: "," });
// → { value: "1234.56", floatValue: 1234.56, formattedValue: "$1,234.56" }

// Euro format
parseCurrency("1.234,56€", {
  suffix: "€",
  thousandSeparator: ".",
  decimalSeparator: ",",
});
// → { floatValue: 1234.56 }

formatCompact / parseCompact

Compact number notation (1K, 1M, 1B) with full round-trip support:

import { formatCompact, parseCompact } from "currency-fomatter";

formatCompact(1234567);          // → "1.23M"
formatCompact(2500000000);       // → "2.5B"
formatCompact(1500000, { prefix: "$", decimalScale: 1 }); // → "$1.5M"

// Vietnamese
formatCompact(1500000000, {
  compactDisplay: { thousand: " nghìn", million: " triệu", billion: " tỷ" },
  suffix: " ₫",
});
// → "1.5 tỷ ₫"

// Parse back
parseCompact("2.5M"); // → { value: "2500000", floatValue: 2500000 }

getCurrencyConfig

Auto-configure formatting from ISO 4217 currency codes:

import { getCurrencyConfig } from "currency-fomatter";

getCurrencyConfig("USD");
// → { prefix: "$", decimalScale: 2, fixedDecimalScale: true, thousandSeparator: ",", decimalSeparator: "." }

getCurrencyConfig("JPY");
// → { prefix: "¥", decimalScale: 0, ... }

getCurrencyConfig("VND");
// → { suffix: " ₫", decimalScale: 0, ... }

// Use with component
<CurrencyFormat value={1234.56} {...getCurrencyConfig("GBP")} />
// → £1,234.56

Locale Support

Auto-detect from browser

import { getAutoLocaleConfig } from "currency-fomatter";

// Detects user's browser locale automatically
const config = getAutoLocaleConfig("USD");
<CurrencyFormat value={1234.56} {...config} />

Any locale via Intl.NumberFormat

import { detectLocaleFormat, createLocaleConfig, formatWithIntl } from "currency-fomatter";

// Thai
detectLocaleFormat("th-TH", "THB");
// → { thousandSeparator: ",", decimalSeparator: ".", prefix: "฿", ... }

// Arabic
detectLocaleFormat("ar-SA", "SAR");

// Direct Intl formatting
formatWithIntl(1234567.89, "de-DE", { style: "currency", currency: "EUR" });
// → "1.234.567,89 €"

Static presets

Pre-configured: en-US, vi-VN, de-DE, ja-JP, en-IN, fr-FR, zh-CN, ko-KR, pt-BR, en-GB

import { getLocaleConfig, getFormatOptionsFromLocale } from "currency-fomatter";

<CurrencyFormat value={1234567} {...getFormatOptionsFromLocale("vi-VN")} />
// → 1.234.567 ₫

Custom locale registry

import { registerLocale, unregisterLocale } from "currency-fomatter";

registerLocale("bitcoin", {
  locale: "bitcoin",
  prefix: "₿ ",
  thousandSeparator: " ",
  decimalSeparator: ".",
  decimalScale: 8,
});

// Use it anywhere
<CurrencyFormat value={0.00123456} {...getFormatOptionsFromLocale("bitcoin")} />

unregisterLocale("bitcoin");

Hooks

useCurrencyInput (Headless)

A truly headless hook that works with any <input> element. No dependency on <CurrencyFormat />.

import { useCurrencyInput } from "currency-fomatter";

function PriceInput() {
  const { value, formattedValue, getInputProps, setValue, reset, clear } = useCurrencyInput({
    currency: "USD",         // Auto-configures prefix, decimals from ISO 4217
    initialValue: 1000,
    onValueChange: (values) => console.log(values.floatValue),
  });

  return (
    <div>
      <input {...getInputProps()} />
      <p>Raw: {value} | Display: {formattedValue}</p>
      <button onClick={() => setValue(2000)}>Set $2000</button>
      <button onClick={reset}>Reset</button>
      <button onClick={clear}>Clear</button>
    </div>
  );
}

Works with any UI library:

// Material UI
<TextField {...getInputProps()} label="Price" />

// Chakra UI
<Input {...getInputProps()} />

// Ant Design
<AntInput {...getInputProps()} />

Options: currency, locale, initialValue, onValueChange, plus all FormatCurrencyOptions (prefix, suffix, decimalScale, etc.). Direct props override currency/locale defaults.

useCurrencyFormat

Higher-level hook that returns props for the <CurrencyFormat /> component:

import { useCurrencyFormat, CurrencyFormat } from "currency-fomatter";

function PriceInput() {
  const { value, formattedValue, inputProps, reset, clear } = useCurrencyFormat({
    locale: "en-US",
    initialValue: 1000,
  });

  return (
    <div>
      <CurrencyFormat {...inputProps} />
      <p>Raw: {value} | Display: {formattedValue}</p>
    </div>
  );
}

PatternFormat

A focused component for pattern-based formatting (phone, card, date). Cleaner API than using CurrencyFormat with format prop.

import { PatternFormat } from "currency-fomatter";

// Phone number
<PatternFormat format="+1 (###) ###-####" mask="_" />

// Credit card
<PatternFormat format="#### #### #### ####" mask="_" />

// Date with per-position masks
<PatternFormat format="##/##/####" mask={["D","D","M","M","Y","Y","Y","Y"]} />

// Show mask on empty
<PatternFormat format="+1 (###) ###-####" mask="_" allowEmptyFormatting />
// → +1 (___) ___-____

PatternFormat accepts: format, mask, allowEmptyFormatting, value, defaultValue, onValueChange, displayType, customInput, and all standard input props.

Component API

Props

Prop	Type	Default	Description
value	string | number	—	Controlled input value
defaultValue	string | number	—	Uncontrolled initial value
format	string | Function	—	Pattern ("+1 (###) ###-####") or custom format function
decimalScale	number	—	Max decimal places
decimalSeparator	string	"."	Decimal separator
thousandSeparator	string | boolean	","	Thousand separator (true = ",")
thousandSpacing	"2" | "2s" | "3" | "4"	"3"	Grouping pattern
thousandsGroupStyle	"thousand" | "lakh" | "wan" | "none"	—	Human-readable grouping alias
mask	string | string[]	" "	Mask for empty format positions
prefix	string	""	Text before number ("$")
suffix	string	""	Text after number ("%")
allowNegative	boolean	true	Allow negative values
allowEmptyFormatting	boolean	false	Show prefix/suffix when empty
allowedDecimalSeparators	string[]	—	Extra keys treated as decimal separator
fixedDecimalScale	boolean	false	Always show decimal places
isNumericString	boolean	false	Treat value as numeric string
isAllowed	(values) => boolean	—	Custom validation
onValueChange	(values, sourceInfo) => void	—	Value change callback
inputMode	"numeric" | "decimal" | "text"	auto	Mobile keyboard type (auto-detected)
displayType	"input" | "text"	"input"	Render mode
customInput	ComponentType	—	Custom input component
renderText	(value, props) => ReactNode	—	Custom text renderer
type	"text" | "tel"	"text"	Input type
name	string	—	Field name
getInputRef	(el) => void	—	Get input element ref

thousandsGroupStyle

Human-readable alias for thousandSpacing:

Style	Equivalent	Example
"thousand"	"3"	1,234,567
"lakh"	"2s"	12,34,567
"wan"	"4"	123,4567
"none"	—	1234567

allowedDecimalSeparators

Accept multiple keys as decimal input (useful for European keyboards):

<CurrencyFormat
  decimalSeparator=","
  allowedDecimalSeparators={[",", "."]}
  // User can press either . or , to type a decimal
/>

ValueObject

interface ValueObject {
  formattedValue: string;  // "$1,234.56"
  value: string;           // "1234.56"
  floatValue: number;      // 1234.56
  name?: string;           // Field name if provided
}

onValueChange sourceInfo

onValueChange={(values, sourceInfo) => {
  // sourceInfo.source: "event" (user typed) | "prop" (value prop changed)
  // sourceInfo.event: the original DOM event (when source is "event")
  if (sourceInfo?.source === "event") {
    // Only react to user input, not programmatic changes
  }
}}

Examples

Phone number

<PatternFormat format="+1 (###) ###-####" mask="_" />
// → +1 (555) 123-4567

Credit card

<PatternFormat format="#### #### #### ####" mask="_" />
// → 4111 1111 1111 1111

Percentage with max

<CurrencyFormat
  suffix="%"
  decimalScale={2}
  isAllowed={(values) => (values.floatValue ?? 0) <= 100}
/>

Display as text

<CurrencyFormat
  value={9999.99}
  displayType="text"
  thousandSeparator=","
  prefix="$"
/>
// Renders: <span role="status" aria-live="polite">$9,999.99</span>

Custom input (Material UI, etc.)

<CurrencyFormat
  value={1000}
  customInput={TextField}
  thousandSeparator=","
  prefix="$"
/>

Form Library Integration

react-hook-form

import { useForm } from "react-hook-form";
import { CurrencyFormat } from "currency-fomatter";

function MyForm() {
  const { register, handleSubmit, setValue } = useForm();

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <CurrencyFormat
        {...register("price")}
        thousandSeparator=","
        prefix="$"
        onValueChange={(values, sourceInfo) => {
          if (sourceInfo?.source === "event") {
            setValue("price", values.floatValue);
          }
        }}
      />
    </form>
  );
}

Accessibility

• inputMode auto-detected for mobile keyboards (numeric/decimal)
• displayType="text" renders with role="status" and aria-live="polite"
• All aria-* props passed through to the input element
• IME composition support for CJK (Chinese, Japanese, Korean) input
• Home/End keys respect prefix/suffix boundaries
• Disabled/readOnly states properly handled

TypeScript

Full type exports available:

import type {
  CurrencyFormatProps,
  PatternFormatProps,
  ThousandsGroupStyle,
  ValueObject,
  ThousandSpacing,
  FormatCurrencyOptions,
  ParseCurrencyOptions,
  CompactDisplayOptions,
  FormatCompactOptions,
  UseCurrencyFormatOptions,
  UseCurrencyFormatReturn,
  UseCurrencyInputOptions,
  UseCurrencyInputReturn,
  LocaleConfig,
  CurrencyInfo,
  FormatFunction,
  RemoveFormattingFunction,
  IsAllowedFunction,
  OnValueChangeFunction,
  RenderTextFunction,
} from "currency-fomatter";

License

MIT