Skip to content

Latest commit

 

History

History
272 lines (193 loc) · 8.6 KB

componentDocumentation.md

File metadata and controls

272 lines (193 loc) · 8.6 KB
Raw

Text Mask documentation

mask

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

mask array

The way to define a mask in Text Mask is through 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. 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 enter only 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.

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.

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.

placeholderChar

The placeholder character represents the fillable spot in the mask. The default placeholder character is underscore, _.

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.

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. config is an object that contains all the user configurations for Text Mask (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.

onReject

You can provide an onReject callback function which will be called when the user tries to enter a character that ends up being rejected either by the mask or by the pipe and not displayed on the input element.

The onReject callback will receive an object with the following keys:

  1. conformedValue (string): containing the conformed value
  2. maskRejection (boolean): true if the rejection was due to mask incompatibility
  3. pipeRejection (boolean): true if the rejection was decided by the pipe

onAccept

You can provide an onAccept callback function which will be called when the user enters a character that is accepted and displayed on the input element.

Included conformToMask

conformToMask is the function that Text Mask uses to transform text to the given mask.

Importing it

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

import textMask, {conformToMask} from 'where-you-import-text-mask-from'

Note to Ember users: conformToMask is not included in the Ember package. If you need it, please open an issue.

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:

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

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

console.log(conformedPhoneNumber.conformedValue) // prints (555) 123-4444

Known issues

Supported <input> types

Please note that Text Mask supports input type 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 the appropriate input mask.

Updating the mask or other values after initialization

Once Text Mask has been initialized on an input field, it's not possible to change the mask or other configurations. In frameworks such as React or Ember, you may expect that you can hot-swap values, but that would not work with Text Mask. See this page for some workarounds for this limitation.