npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@thaborach/react-text-mask

v1.0.11

Published

A masked React Input component

Downloads

491

Readme

@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

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

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:

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

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,

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

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": "(123) 123-1234",
  "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 (555) 123-4444

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!