react-input

The library allows you to apply input masks to input elements using two primary methods: a pre-built InputMask component or a useMask hook.

• InputMask component: A standard input element with built-in masking logic. It is ideal for standard use cases and supports integration with custom components via the component prop.
• useMask hook: A hook that returns a ref which must be attached to a standard HTML input element. This is useful when you want to use your own existing input components or elements.

A key design principle is that the library only relies on user-supplied characters, meaning you can safely include any character in the mask without unexpected behavior.

// Using the component
<InputMask mask="+0 (___) ___-__-__" replacement={{ _: /\d/ }} />

// Using the hook
const inputRef = useMask({
  mask: '+0 (___) ___-__-__',
  replacement: { _: /\d/ },
});
<input ref={inputRef} />

There are two ways to integrate with Material UI (MUI) components like TextField:

Option 1: Using inputComponent

Create a component wrapped in forwardRef that returns an InputMask. Pass this to the inputComponent property of the MUI InputProps.

Option 2: Using the useMask hook

Use the useMask hook to generate a ref and pass it directly to the inputRef property of the MUI component. This is often the cleaner approach for hook-based integration.

// Option 1: inputComponent
import { forwardRef } from 'react';
import { InputMask, type InputMaskProps } from '@react-input/mask';
import { TextField } from '@mui/material';

const ForwardedInputMask = forwardRef<HTMLInputElement, InputMaskProps>((props, forwardedRef) => {
  return <InputMask ref={forwardedRef} mask="___-___" replacement="_" {...props} />;
});

export default function App() {
  return (
    <TextField
      InputProps={{ inputComponent: ForwardedInputMask }}
    />
  );
}

// Option 2: useMask hook
import { useMask } from '@react-input/mask';
import { TextField } from '@mui/material';

export default function App() {
  const inputRef = useMask({ mask: '___-___', replacement: '_' });

  return <TextField inputRef={inputRef} />;
}

The @react-input/number-format package provides full TypeScript support. You can import types directly from @react-input/number-format or @react-input/number-format/types.

Property Type Support

InputNumberFormat adapts its props based on whether you are using it as a standard input or as a Higher-Order Component (HOC) via the component prop:

1. Standard Input: By default, it behaves like an input element and supports all React.InputHTMLAttributes<HTMLInputElement>.
2. Custom Component: If you pass a component prop, it merges NumberFormatOptions with the props of your integrated component.

Fixing Type Inference for Rest Parameters

If you are passing ...rest props (e.g., from a component with any types), TypeScript might fail to correctly infer the types for the component and its properties. To fix this, pass your component's type explicitly to the InputNumberFormat generic.

import { InputNumberFormat } from '@react-input/number-format';
import { CustomInput } from './CustomInput';

export default function Component(props: any) {
  // Pass the component type explicitly to fix inference issues
  return <InputNumberFormat<typeof CustomInput> component={CustomInput} {...props} />;
}

The @react-input/number-format package offers two primary ways to implement number formatting in React applications:

1. InputNumberFormat Component: A standard input element enhanced with formatting logic. This is the preferred method if you want to use the component as a Higher-Order Component (HOC) to integrate with custom components or if you want additional capabilities.
2. useNumberFormat Hook: A hook that returns a ref which must be attached to a standard input element. This is ideal for when you want to maintain full control over the underlying DOM element.

Both methods use the Intl.NumberFormat constructor for localization. For consistent behavior, ensure the type property of the input is set to "text" (the default). Using other types will disable formatting and trigger a console warning.

import { InputNumberFormat } from '@react-input/number-format';

// Using the Component
export default function App() {
  return <InputNumberFormat locales="en" maximumFractionDigits={2} />;
}

// Using the Hook
import { useNumberFormat } from '@react-input/number-format';

export default function App() {
  const inputRef = useNumberFormat({
    locales: 'en',
    maximumFractionDigits: 2,
  });

  return <input ref={inputRef} />;
}

To support controlled inputs, @react-input/number-format does not modify the value passed to the input element. This means the state value must exactly match the formatted value displayed in the input.

If your state contains unformatted numbers, use the format utility to convert the value into the correct formatted string before passing it to the value prop. Failure to do so will result in a console warning.

For uncontrolled inputs, the library handles formatting automatically upon initialization.

import { useState } from 'react';
import { useNumberFormat, format } from '@react-input/number-format';

const options = {
  locales: 'en',
  maximumFractionDigits: 2,
};

export default function App() {
  const inputRef = useNumberFormat(options);
  // Use format() to ensure the initial state matches the expected formatted string
  const defaultValue = format(123456789, options);

  const [value, setValue] = useState(defaultValue); 

  return <input ref={inputRef} value={value} onChange={(event) => setValue(event.target.value)} />;
}

When upgrading @react-input/number-format from version 1 to version 2, note the following breaking changes:

Removal of onNumberFormat and input-number-format event

To ensure better coordination with React's event system, the onNumberFormat method and the input-number-format event have been removed. You should now use the standard React onChange event.

Accessing numeric values

Instead of accessing data via the detail property of an onNumberFormat event, use the provided utility functions (like unformat) inside a standard onChange handler to extract the numeric value.

// OLD (v1)
<InputNumberFormat
  locales={locales}
  onNumberFormat={(event) => {
    const { value, number } = event.detail;
  }}
/>

// NEW (v2)
import { InputNumberFormat, unformat } from '@react-input/number-format';

<InputNumberFormat
  locales={locales}
  onChange={(event) => {
    const value = event.target.value;
    const number = Number(unformat(value, locales));
  }}
/>