react-native-format-kit

Currency input utilities for React Native with controlled formatting, masking, validation, display helpers, and styling hooks built on Intl.NumberFormat. No external deps beyond React/React Native.

Intl note: On older Android versions you may need an Intl polyfill (e.g. @formatjs/intl-numberformat).

Installation

npm install react-native-format-kit

API Overview

• Components: CurrencyInput (editable), CurrencyText (display-only)
• Hook: useCurrencyInput
• Utilities: formatCurrency, parseCurrencyFromDigits, stripToDigits, getDecimalSeparator

CurrencyInput

A controlled TextInput that formats on every change and keeps the caret at the end.

Props

| Prop | Type | Required | Default | Notes | | --- | --- | --- | --- | --- | | currency | string | Yes | — | ISO currency code | | value | number \| null | Yes | — | Controlled value | | onChangeValue | (value: number \| null) => void | Yes | — | Fired on parsed value change | | locale | string | No | device/runtime | Locale for Intl.NumberFormat | | fractionDigits | number | No | 2 | Legacy single min/max fraction setting | | minimumFractionDigits | number | No | fractionDigits or 2 | Formatting only | | maximumFractionDigits | number | No | fractionDigits or 2 | Formatting and parsing scale | | mask | "currency" \| "none" | No | "currency" | currency shows formatted value; none shows raw digits with locale decimal | | minimumValue | number | No | — | Clamp lower bound | | maximumValue | number | No | — | Clamp upper bound | | maxDigits | number | No | — | Caps integer digits; extras ignored and raise error | | allowNegative | boolean | No | false | - toggles sign when true; otherwise ignored/clamped | | validate | (value: number \| null) => string \| null | No | — | Custom validation message | | error | string \| null | No | — | External error overrides internal/custom | | onValidationError | (message: string \| null) => void | No | — | Fires when effective error changes | | showErrorText | boolean | No | false | Renders inline error | | onChangeText | (formatted: string) => void | No | — | Formatted string change | | onChangeRawText | (rawDigits: string) => void | No | — | Digits-only change | | keyboardType | TextInputProps["keyboardType"] | No | "numeric" | Override if needed | | testID, accessibilityLabel | string | No | — | Passed through | | Other TextInputProps | — | No | — | Forwarded except value, onChangeText, keyboardType |

Styling props

| Prop | Type | Default | Notes | | --- | --- | --- | --- | | defaultBorderColor | string | #ccc | Idle border | | focusBorderColor | string | #2d7ff9 | Focused border | | errorBorderColor | string | #d14343 | Error border | | containerStyle | StyleProp<ViewStyle> | — | Outer wrapper | | inputContainerStyle | StyleProp<ViewStyle> | — | Border container | | inputContainerFocusedStyle | StyleProp<ViewStyle> | — | Applied on focus | | inputContainerErrorStyle | StyleProp<ViewStyle> | — | Applied on error | | inputStyle | StyleProp<TextStyle> | — | TextInput styling | | label | string | — | Shown as placeholder; floats on focus/value | | floatingLabel | boolean | true | Toggle floating behavior | | labelStyle | StyleProp<TextStyle> | — | Label text styling | | labelContainerStyle | StyleProp<ViewStyle> | — | Label wrapper styling | | labelBackgroundColor | string | white | Background behind floated label | | errorTextStyle | StyleProp<TextStyle> | — | Inline error text; default color #d14343, fontSize 14 | | errorContainerStyle | StyleProp<ViewStyle> | — | Inline error container; default marginTop 6 |

Behavior highlights

• Digits-only parsing; non-digits ignored. - toggles sign only when allowNegative is true.
• Clearing input sets value to null.
• mask="currency" shows Intl-formatted currency. mask="none" shows raw digits with locale decimal separator (no symbol/grouping).
• minimumFractionDigits/maximumFractionDigits control formatting; parsing uses maximumFractionDigits.

Usage

<CurrencyInput
  currency="USD"
  locale="en-US"
  value={value}
  onChangeValue={setValue}
  onChangeText={(t) => console.log("formatted", t)}
  onChangeRawText={(d) => console.log("digits", d)}
  allowNegative
  maxDigits={6}
  minimumFractionDigits={0}
  maximumFractionDigits={2}
  showErrorText
  label="Amount"
  defaultBorderColor="#ddd"
  focusBorderColor="#2d7ff9"
  errorBorderColor="#e55353"
  inputContainerStyle={{ backgroundColor: "#fafafa" }}
  labelStyle={{ color: "#444" }}
/>

CurrencyText

Display-only formatter for currency values.

• value: number | null (required)
• currency: string (required)
• locale?: string
• fractionDigits?, minimumFractionDigits?, maximumFractionDigits?
• placeholder?: string
• Plus all TextProps

<CurrencyText value={value} currency="EUR" locale="de-DE" placeholder="-" />

Hook: useCurrencyInput

Logic-only hook for parsing/formatting/validation/masking.

Options

• Required: currency: string
• Optional: value?: number | null, locale?, fractionDigits?, minimumFractionDigits?, maximumFractionDigits?, minimumValue?, maximumValue?, allowNegative?, maxDigits?, mask?, validate?

Returns

• value: number | null
• text: string
• rawDigits: string
• error: string | null
• handleChangeText(text: string)
• setValue(value: number | null)

const { text, value, rawDigits, error, handleChangeText, setValue } = useCurrencyInput({
  currency: "USD",
  locale: "en-US",
  allowNegative: true,
  maximumFractionDigits: 2,
  maxDigits: 6,
})

Utilities

import {
  formatCurrency,
  parseCurrencyFromDigits,
  stripToDigits,
  getDecimalSeparator,
} from "react-native-format-kit"

formatCurrency(12.34, { currency: "USD", locale: "en-US", minimumFractionDigits: 2, maximumFractionDigits: 2 })

parseCurrencyFromDigits("1234", {
  currency: "USD",
  maximumFractionDigits: 2,
  allowNegative: true,
  isNegative: true,
  minimumValue: 0,
  maximumValue: 100,
  maxDigits: 5,
})

stripToDigits("€1,234.56") // "123456"
getDecimalSeparator("de-DE") // ","

Validation rules

• maxDigits caps integer digits; extra integer digits are ignored and trigger "Maximum digits is X".
• allowNegative=false clamps negatives to min (default 0); - is ignored.
• minimumValue / maximumValue clamp the value; internal errors reflect bounds.
• validate(value) can return a custom error string; error prop overrides internal/custom.
• onValidationError fires whenever the effective error message changes.