CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-react-number-format

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

—

Pending
Overview
Eval results
Files

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;

Install with Tessl CLI

npx tessl i tessl/npm-react-number-format
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-number-format@5.4.x
Publish Source
CLI
Badge
tessl/npm-react-number-format badge