FormatInput

pro

FormatInput formats numeric entry as the user types, with numeric, pattern-mask, and custom-format variants over the shared Input.

Get the code

Installation

Add this component with the NateUI CLI.

npx nateui@latest add FormatInput

pnpm dlx nateui@latest add FormatInput

yarn dlx nateui@latest add FormatInput

Examples

Numeric Formats

Get the code

Discount

Units in stock

Affix

Get the code

Value: — — the $ became part of the text

kgValue: — — the icon and “kg” are decoration only

Stepper

Get the code

Pattern

Get the code

Phone number

ZIP + 4

Custom Format

Get the code

Controlled

Get the code

Raw value: 1200

API

FormatInput.Numeric, FormatInput.Pattern, and FormatInput.Custom each wrap a react-number-format primitive over the shared Input surface. All three take inputPrefix/inputSuffix instead of Input's own prefix/suffix, because Numeric and Custom already use prefix/suffix for text that's baked into the formatted value itself.

FormatInput.Numeric

Prop	Description	Type	Default
`value`	Controlled numeric value.	`number \| string \| null`	—
`defaultValue`	Initial value for uncontrolled usage.	`number \| string \| null`	—
`onValueChange`	Fires with the parsed float, raw digits, and formatted string whenever the value changes.	`(values: NumberFormatValues, sourceInfo: SourceInfo) => void`	—
`thousandSeparator`	Character used to group digits, or `true` for a comma.	`boolean \| string`	—
`decimalSeparator`	Character shown before the decimal digits.	`string`	`'.'`
`decimalScale`	Number of digits kept after the decimal separator.	`number`	—
`fixedDecimalScale`	Pads with trailing zeros to always show `decimalScale` digits.	`boolean`	`false`
`allowNegative`	Allows a leading minus sign.	`boolean`	`true`
`allowLeadingZeros`	Keeps leading zeros instead of stripping them.	`boolean`	`false`
`thousandsGroupStyle`	Digit grouping convention.	`'thousand' \| 'lakh' \| 'wan' \| 'none'`	`'thousand'`
`prefix`	Text baked into the formatted value, before the digits (for example `'$'`).	`string`	—
`suffix`	Text baked into the formatted value, after the digits (for example `'%'`).	`string`	—
`stepper`	Replaces the suffix slot with built-in increment/decrement buttons. Requires controlled `value` + `onValueChange`; the buttons have no effect with only `defaultValue`.	`boolean`	`false`
`min`	Lowest value the stepper buttons will reach.	`number`	`0`
`max`	Highest value the stepper buttons will reach.	`number`	`Infinity`
`step`	Amount each stepper click adds or subtracts.	`number`	`1`
`inputPrefix`	Decorative content in Input's prefix slot; not part of the value.	`string \| ReactNode`	—
`inputSuffix`	Decorative content in Input's suffix slot; not part of the value. Ignored when `stepper` is true.	`string \| ReactNode`	—
`size`	Control size.	`ControlSize`	`'md'`
`disabled`	Prevents editing and applies disabled control styling.	`boolean`	—
`...rest`	Remaining `NumericFormat` props from `react-number-format`, plus native input attributes.	`NumericFormatProps`	—

FormatInput.Pattern

Prop	Description	Type	Default
`format`	Pattern string where each `patternChar` is a fillable digit slot (for example `'(###) ###-####'`).	`string`	—
`mask`	Placeholder character shown in empty digit slots, or one character per slot.	`string \| string[]`	—
`patternChar`	Character in `format` that marks a fillable slot.	`string`	`'#'`
`allowEmptyFormatting`	Shows the literal pattern characters even before any digit is entered.	`boolean`	`false`
`value`	Controlled value.	`string \| number \| null`	—
`defaultValue`	Initial value for uncontrolled usage.	`string \| number \| null`	—
`onValueChange`	Fires with the parsed digits and formatted string whenever the value changes.	`(values: NumberFormatValues, sourceInfo: SourceInfo) => void`	—
`inputPrefix`	Decorative content in Input's prefix slot.	`string \| ReactNode`	—
`inputSuffix`	Decorative content in Input's suffix slot.	`string \| ReactNode`	—
`size`	Control size.	`ControlSize`	`'md'`
`disabled`	Prevents editing and applies disabled control styling.	`boolean`	—
`...rest`	Remaining `PatternFormat` props from `react-number-format`, plus native input attributes.	`PatternFormatProps`	—

FormatInput.Custom

Prop	Description	Type	Default
`format`	Transforms raw characters into the displayed string.	`(value: string) => string`	identity
`removeFormatting`	Strips a formatted string back to raw characters, typically while editing.	`(value: string, changeMeta?: ChangeMeta) => string`	digits-only
`getCaretBoundary`	Marks which caret positions are safe to land on inside the formatted string.	`(formattedValue: string) => boolean[]`	numeric-boundary heuristic
`value`	Controlled value.	`string \| number \| null`	—
`defaultValue`	Initial value for uncontrolled usage.	`string \| number \| null`	—
`onValueChange`	Fires with the parsed value and formatted string whenever the value changes.	`(values: NumberFormatValues, sourceInfo: SourceInfo) => void`	—
`inputPrefix`	Decorative content in Input's prefix slot.	`string \| ReactNode`	—
`inputSuffix`	Decorative content in Input's suffix slot.	`string \| ReactNode`	—
`size`	Control size.	`ControlSize`	`'md'`
`disabled`	Prevents editing and applies disabled control styling.	`boolean`	—
`...rest`	Remaining `NumberFormatBase` props from `react-number-format`, plus native input attributes.	`NumberFormatBaseProps`	—

NumericFormatProps, PatternFormatProps, and NumberFormatBaseProps are react-number-format's own types; see the library's docs for its full option list.

Types

type NumberFormatValues = {
  floatValue: number | undefined;
  formattedValue: string;
  value: string;
};
 
type SourceInfo = {
  event?: SyntheticEvent<HTMLInputElement>;
  source: 'event' | 'prop';
};
 
type ChangeMeta = {
  from: { start: number; end: number };
  to: { start: number; end: number };
  lastValue: string;
};
 
type ControlSize = 'sm' | 'md' | 'lg';