React Text Mask

5.5.0 · active · verified Sun Apr 19

This package provides a React component, `<MaskedInput>`, for creating input fields that enforce specific formatting patterns on user input. It is part of the larger `text-mask` ecosystem, which offers similar masking solutions for various JavaScript frameworks and vanilla JS. The current stable version for `react-text-mask` is 5.5.0. Releases are typically driven by fixes and minor enhancements across its different framework-specific packages (e.g., React, Vue, Angular), rather than a fixed cadence. A key differentiator is its highly configurable `mask` prop, which accepts an array of characters and regular expressions, allowing for flexible pattern definition. It also supports a `render` prop for advanced customization, enabling integration with styled-components or other custom input wrappers. It aims for full compatibility with standard HTML `<input>` attributes like `className`, `placeholder`, `onBlur`, and `onChange`, simplifying its adoption into existing forms.

Common errors

```
Warning: Failed prop type: Invalid prop `mask` of type `string` supplied to `MaskedInput`, expected `array`.
```
cause The `mask` prop was provided as a string instead of an array.

fix The `mask` prop must be an array of characters and/or regular expressions, or a function that returns such an array. Wrap the mask pattern in an array, e.g., `mask={['(', /[1-9]/, /\d/, /\d/, ')']}`.
```
Input value cannot be controlled while using a mask.
```
cause `react-text-mask` internally manages the input's value to apply the mask. Directly controlling the `value` prop simultaneously with user input can conflict with this internal state management.

fix Allow `react-text-mask` to manage the input's value. Use the `onChange` event handler to retrieve the formatted or raw value, but avoid setting the `value` prop after initial mount unless implementing complex controlled component logic with careful state synchronization.
```
TypeError: 'mask' must be an array or a function.
```
cause The value provided to the `mask` prop is neither an array nor a function.

fix Ensure the `mask` prop is either an array (e.g., `['a', 'b', 'c']`) or a function that returns an array or `false`. This error often occurs if `mask` is `undefined`, `null`, or an incorrect primitive type.

Warnings

gotcha The `guide` prop defaults to `true`, which displays the mask's placeholder characters even when the input is empty. If you prefer the input to be completely empty until the user types, set `guide={false}`.
Fix: Set `guide={false}` on the `MaskedInput` component.
gotcha The `mask` prop expects an array of characters and/or regular expressions. Providing a string directly, or an improperly structured array, will lead to unexpected behavior or errors.
Fix: Ensure `mask` is an array, e.g., `mask={['(', /[1-9]/, ..., ')']}`. For complex dynamic masks, you can provide a function that returns a mask array.

Install

npm install react-text-mask npm
yarn add react-text-mask yarn
pnpm add react-text-mask pnpm

Imports

MaskedInput

wrong:

import { MaskedInput } from 'react-text-mask'

correct:

import MaskedInput from 'react-text-mask'

MaskedInput is a default export.

MaskedInput (CJS)
```
const MaskedInput = require('react-text-mask')
```
CommonJS require pattern for Node.js or older bundlers.

Quickstart

Demonstrates basic usage of `MaskedInput` for phone number formatting, including placeholder, guide, and event handlers.

import React from 'react';
import MaskedInput from 'react-text-mask';

const PhoneNumberInput = () => (
  <div>
    <label htmlFor="phone-input">Phone Number:</label>
    <MaskedInput
      mask={['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]}
      className="form-control"
      placeholderChar="_"
      placeholder="(   )    -    "
      guide={true}
      id="phone-input"
      onBlur={() => console.log('Input blurred')}
      onChange={(e) => console.log('Input changed:', e.target.value)}
    />
  </div>
);

export default PhoneNumberInput;

view raw JSON →