!GitHub Actions Workflow Status
!GitHub License

@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

$3

npm:

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

yarn:

`bash
yarn add @thaborach/react-text-mask
`

$3

`js
import React from 'react';
import { MaskedInput } from 'react-text-mask';

export default function TelephoneInput() {
return (



);
}
`

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

For example, the following works:

`js
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)

$3

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 (555) 392-4932, could be:

`js
['(', /[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.

`js
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.

$3

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.

$3

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.

$3

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.

$3

The placeholder character represents the fillable spot in the mask.

It is set to _ (underscore) by default.

For example, with mask...

`js
['(', /[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.

$3

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.

$3

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.

$3

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

If no render prop is passed, a normal is rendered.

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

`js
mask={['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/]}
placeholder='Enter a phone number'
id='my-input-id'
render={(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

$3

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

`js
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:

`json
{
"conformedValue": "(123) 123-1234",
"meta": {
"someCharsRejected": false
}
}
`

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

`js
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 (555) 123-4444
``

$3

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!