@thaborach/react-text-mask

@thaborach/react-text-mask

React Text Mask is an input mask library. It can create input masks for phone, date, currency, zip code, percentage, email, and literally anything!

• It is very configurable and allows you to create any type of input mask with minimal APIs.

• It supports pasting, browser auto-fill, and all operations that a user would expect while interacting with an input field.

• It works on mobile, has no 3rd party dependencies, and has a tiny footprint (less than 4KB gzipped).

It is forked from text mask which is deprecated and no longer being maintained.

Check out the demo

Table of Contents

• Installation and usage
• Properties
• Utilities
• Contributing
• Questions, suggestions, or feature requests

Installation and usage

Installation

npm:

npm i @thaborach/react-text-mask --save

yarn:

yarn add @thaborach/react-text-mask

Usage

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

export default function TelephoneInput(){
    
    return (
        <div>
            <MaskedInput
                type='tel'
                mask={['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]}
            />
        </div>
    )
}

<MaskedInput/> is fully compatible with <input/> element. So, you can pass it CSS classes, a placeholder attribute, or even an onBlur handler.

For example, the following works:

<MaskedInput
  mask={['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]}
  type="tel"
  className="form-control"
  placeholder="Enter a phone number"
  guide={false}
  id="my-input-id"
  onBlur={() => {}}
  onChange={() => {}}
/>

Properties

Text Mask accepts the following values as props:

• mask (array, function, object or boolean) (required)
• type ('text' | 'tel' | 'url' | 'password' | 'search') (optional)
• guide (boolean) (optional)
• pipe (function) (optional)
• placeholderChar (string) (optional)
• keepCharPositions (boolean) (optional)
• showMask (boolean) (optional)
• render (function) (optional)

mask

mask is an array, function or object that defines how the user input is going to be masked.

mask array

Easiest way to define a mask is to use an array.

Each element in the array has to be either a string or a regular expression. Each string is a fixed character in the mask and each regular expression is a placeholder that accepts user input.

The regular expression will be used to test user input and either allow it or reject it.

For example, a mask for a U.S. based phone number such as [phone], could be:

['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]

That means the user can only enter a number between 1 and 9 in the first placeholder, and only a digit in the placeholders after that.

Any valid regular expressions should work.

mask function

You can also pass a function as the mask. The function will receive the user input at every change. The function is expected to return a mask array as described above.

const mask = function(rawValue) {
  // add logic to generate your mask array
  return [ /*your mask array*/ ]
}

This feature is useful when we want to format a user input of unknown length, such as formatting a number to currency or formatting a string to email address mask.

For an example of a mask function, see the source code of createNumberMask, which is a Text Mask addon.

mask object

Coming soon...

mask boolean

It is possible to set the mask to false to disable masking completely.

type

It is set to text by default.

We only support input types of text, tel, url, password, and search. Due to a limitation in browser API, other input types, such as email or number, cannot be supported. However, it is normal to let the user enter an email or a number in an input type text combined with the appropriate input mask.

guide

guide is a boolean that tells the component whether to be in guide or no guide mode.

It is set to true by default.

Guide mode	No-guide mode
When guide is true, Text Mask always shows both placeholder characters and non-placeholder mask characters.	When guide is false, Text Mask doesn't print out placeholder characters and only adds mask characters when the user reaches them as they're typing.

pipe

You can provide a pipe function that will give you the opportunity to modify the conformed value before it is displayed on the screen.

The pipe function receives:

1. conformedValue
2. config

The conformedValue is the value that the user entered after it has been conformed. The config is an object that contains all the user configurations for the component (the ones detailed on this page).

The pipe function must return one of the following: false, string, or object.

Return false to reject the new conformed value and keep the input field from changing.

If the pipe modifies the string without adding new characters, for example, changing letter capitalization or removing characters, it should return the modified string.

If the pipe adds new characters to the string, it must return an object with the following keys:

1. value: the new string
2. indexesOfPipedChars: array of integers, which contains the indexes of all the characters that were added by the pipe to the conformed value

For an example of a pipe, see the code for createAutoCorrectedDatePipe which is a Text Mask addon.

placeholderChar

The placeholder character represents the fillable spot in the mask.

It is set to _ (underscore) by default.

For example, with mask...

['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]

...the user would fill out (___) ___-____.

You can pass a different placeholder character. For example, the unicode character U+2000 would make the mask above look like (   )    -    .

In JavaScript, you would pass such unicode character as '\u2000'.

📍 Note: you cannot use a mask that has a placeholder character hard-coded in it. That is, since the default placeholder character is _, you cannot have a mask that looks like _111_ unless you pass placeholderChar that is not _ and doesn't exist in your mask.

keepCharPositions

keepCharPositions changes the general behavior of the Text Mask component.

It is set to false by default,

keepCharPositions is set to true	keepCharPositions is set to false
When true, adding or deleting characters will not affect the positions of existing characters.	When false, adding characters causes existing characters to advance. And deleting characters causes existing characters to move back.

showMask

showMask is a boolean that tells the component to display the mask as a placeholder in place of the regular placeholder when the input element value is empty.

render

For advanced use cases, you can customize the rendering of the resultant <input> via a render prop. This is entirely optional.

If no render prop is passed, a normal <input> is rendered.

For example, to use with styled-components, which requires an innerRef:

<MaskedInput
  mask={['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]}
  placeholder="Enter a phone number"
  id="my-input-id"
  render={(ref, props) => (
    <MyStyledInput innerRef={ref} {...props} />
  )}
/>

const MyStyledInput = styled.input`
  background: papayawhip;
`;

Utilities

In addition to the Mask Input component there are additional utility functions that you can utilize, such as:

• conformToMask
• Addons

conformToMask

It is the function that the Masked input component uses to transform text to the given mask.

Importing it

It is included for convenience. So you can import it from the package as follows

import { MaskedInput, conformToMask } from 'react-text-mask';

Using it

conformToMask accepts three arguments:

• text (string) (required)
• mask (array) (required)
• config (object) (optional)

config is these values. The linked variable names have similar names to properties that are described above in this document. So you can learn what each one is for by reading the documentation above.

The return value of conformToMask is an object with the following shape:

{
  "conformedValue": "[phone]",
  "meta": {
    "someCharsRejected": false
  }
}

So, one way to use conformToMask could be as follows:

const phoneNumber = '5551234444'
const phoneNumberMask = ['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]

const conformedPhoneNumber = conformToMask(
  phoneNumber,
  phoneNumberMask,
  {guide: false}
)

console.log(conformedPhoneNumber.conformedValue) // prints [phone]

Add ons

You can easily expand the base functionality of React Text Mask with addons for more mask types. Checkout existing addons.

Contributing

We would love some contributions! Check out this document to get started.

For any questions, suggestions, or feature requests

Please file an issue!