or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

base-component.mdindex.mdnumeric-formatting.mdpattern-formatting.mdreact-hooks.mdutility-functions.md
tile.json

tessl/npm-react-number-format

React component library for formatting numbers in input fields and text display with sophisticated caret engine and customizable patterns.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-number-format@5.4.x

To install, run

npx @tessl/cli install tessl/npm-react-number-format@5.4.0

index.mddocs/

React Number Format

React Number Format is a sophisticated React component library for formatting numbers in input fields and text display. It provides two main components (NumericFormat and PatternFormat) with a lightweight caret engine that ensures users can only enter text meeting specific numeric or string patterns while providing real-time formatting for display.

Package Information

  • Package Name: react-number-format
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install react-number-format or yarn add react-number-format

Core Imports

import { NumericFormat, PatternFormat, NumberFormatBase } from "react-number-format";

For CommonJS:

const { NumericFormat, PatternFormat, NumberFormatBase } = require("react-number-format");

Import specific utilities:

import { 
  numericFormatter, 
  removeNumericFormat, 
  patternFormatter, 
  removePatternFormat,
  useNumericFormat,
  usePatternFormat
} from "react-number-format";

Basic Usage

NumericFormat Component

import React from "react";
import { NumericFormat } from "react-number-format";

function CurrencyInput() {
  return (
    <NumericFormat
      value={1234.56}
      displayType="input"
      thousandSeparator={true}
      prefix="$"
      decimalScale={2}
      fixedDecimalScale={true}
      onValueChange={(values) => {
        console.log(values.floatValue); // 1234.56
        console.log(values.formattedValue); // $1,234.56
      }}
    />
  );
}

PatternFormat Component

import React from "react";
import { PatternFormat } from "react-number-format";

function PhoneInput() {
  return (
    <PatternFormat
      format="(###) ###-####"
      allowEmptyFormatting
      mask="_"
      onValueChange={(values) => {
        console.log(values.value); // 1234567890
        console.log(values.formattedValue); // (123) 456-7890
      }}
    />
  );
}

Architecture

React Number Format is built around several key components:

  • NumberFormatBase: Core component providing base formatting functionality with customizable format/removeFormatting functions
  • NumericFormat: Specialized component for numeric input with prefix, suffix, thousands separators, and decimal handling
  • PatternFormat: Specialized component for custom string pattern formatting with input masking capabilities
  • Utility Functions: Standalone formatting functions for use without React components
  • React Hooks: useNumericFormat and usePatternFormat hooks for custom implementations
  • Caret Engine: Sophisticated caret positioning system ensuring proper cursor behavior during formatting

Capabilities

Numeric Formatting

Handles numeric input formatting with prefix, suffix, thousands separators, decimal scale control, and international number formatting styles.

function NumericFormat<BaseType = InputAttributes>(
  props: NumericFormatProps<BaseType>
): React.ReactElement;

interface NumericFormatProps<BaseType = InputAttributes> {
  thousandSeparator?: boolean | string;
  decimalSeparator?: string;
  allowedDecimalSeparators?: Array<string>;
  thousandsGroupStyle?: 'thousand' | 'lakh' | 'wan' | 'none';
  decimalScale?: number;
  fixedDecimalScale?: boolean;
  allowNegative?: boolean;
  allowLeadingZeros?: boolean;
  suffix?: string;
  prefix?: string;
}

Numeric Formatting

Pattern Formatting

Provides custom string pattern formatting with input masking for phone numbers, credit cards, dates, and other structured text formats.

function PatternFormat<BaseType = InputAttributes>(
  props: PatternFormatProps<BaseType>
): React.ReactElement;

interface PatternFormatProps<BaseType = InputAttributes> {
  format: string;
  mask?: string | string[];
  allowEmptyFormatting?: boolean;
  patternChar?: string;
}

Pattern Formatting

Base Component System

Core component providing customizable formatting functionality that both NumericFormat and PatternFormat extend.

function NumberFormatBase<BaseType = InputAttributes>(
  props: NumberFormatBaseProps<BaseType>
): React.ReactElement;

interface NumberFormatBaseProps<BaseType = InputAttributes> {
  type?: 'text' | 'tel' | 'password';
  displayType?: 'input' | 'text';
  customInput?: React.ComponentType<BaseType>;
  renderText?: (formattedValue: string, otherProps: Partial<NumberFormatBaseProps>) => React.ReactNode;
  format?: (inputValue: string) => string;
  removeFormatting?: (inputValue: string, changeMeta?: ChangeMeta) => string;
  getInputRef?: ((el: HTMLInputElement) => void) | React.Ref<any>;
  value?: number | string | null;
  defaultValue?: number | string | null;
  valueIsNumericString?: boolean;
  onValueChange?: OnValueChange;
  isAllowed?: (values: NumberFormatValues) => boolean;
  getCaretBoundary?: (formattedValue: string) => boolean[];
  isValidInputCharacter?: (character: string) => boolean;
  isCharacterSame?: IsCharacterSame;
}

Base Component System

Utility Functions

Standalone formatting functions that can be used independently of React components for server-side processing, validation, or custom implementations.

// Numeric formatting utilities
function numericFormatter<BaseType = InputAttributes>(
  numStr: string,
  props: NumericFormatProps<BaseType>
): string;

function removeNumericFormat<BaseType = InputAttributes>(
  value: string,
  changeMeta: ChangeMeta,
  props: NumericFormatProps<BaseType>
): string;

// Pattern formatting utilities  
function patternFormatter<BaseType = InputAttributes>(
  numStr: string,
  props: PatternFormatProps<BaseType>
): string;

function removePatternFormat<BaseType = InputAttributes>(
  value: string,
  changeMeta: ChangeMeta,
  props: PatternFormatProps<BaseType>
): string;

Utility Functions

React Hooks

React hooks for advanced use cases where you need to integrate formatting logic with custom components or complex state management.

function useNumericFormat<BaseType = InputAttributes>(
  props: NumericFormatProps<BaseType>
): NumberFormatBaseProps<BaseType>;

function usePatternFormat<BaseType = InputAttributes>(
  props: PatternFormatProps<BaseType>
): NumberFormatBaseProps<BaseType>;

React Hooks

Core Types

interface NumberFormatValues {
  floatValue: number | undefined;
  formattedValue: string;
  value: string;
}

interface SourceInfo {
  event?: React.SyntheticEvent<HTMLInputElement>;
  source: SourceType;
}

interface ChangeMeta {
  from: { start: number; end: number };
  to: { start: number; end: number };
  lastValue: string;
}

type OnValueChange = (values: NumberFormatValues, sourceInfo: SourceInfo) => void;

enum SourceType {
  event = 'event',
  props = 'prop'
}

type InputAttributes = Omit<
  React.InputHTMLAttributes<HTMLInputElement>,
  'defaultValue' | 'value' | 'children'
>;

type FormatInputValueFunction = (inputValue: string) => string;
type RemoveFormattingFunction = (inputValue: string, changeMeta?: ChangeMeta) => string;

type IsCharacterSame = (compareProps: {
  currentValue: string;
  lastValue: string;
  formattedValue: string;
  currentValueIndex: number;
  formattedValueIndex: number;
}) => boolean;