@cmath10/jmask NPM

JMask - JavaScript Mask component

This package provides a mask component - a reworked version of jQuery-Mask-Plugin, without jQuery (and any other dependency either).

Installation

yarn add @cmath10/jmask

npm i @cmath10/jmask

Usage

Basic example

import JMask from '@cmath10/jmask'

// ...

const el = document.querySelector('input#phone')
const mask = new JMask(el, '+7-000-000-00-00')

JMask constructor arguments:

el - Element - element which will be managed by the mask component;
mask - string - mask to apply;
options - object - optional argument, provides following options:
- clearIfNotMatch - boolean - value from input element will be erased on focus loose, if it wasn't input fully according the specified mask, defaults to false;
- reverse - boolean - if true, mask accounting starts with the last characters, which makes it convenient to enter, for example, financial values, defaults to false;
- exclude - string[] - an array of keys that will be excluded from accounting, needed for non-character keys so that they can be used as usual; by default excluded:
  - alt (both, left & right);
  - backspace
  - ctrl (both, left & right);
  - home;
  - shift (both, left & right);
  - tab;
  - window (left);
  - arrows;
- descriptors - object - custom mask character definitions.

Descriptors

By default, JMask uses descriptors:

0 - for digits 0-9, required, if 0 present in a mask, will reject any characters until a digit is entered;
9 - for digits 0-9, optional, if 9 present in a mask, digit could be skipped;
# - for digits 0-9, allows you to enter digits in unlimited quantities;
A - alphanumeric, a-zA-Z0-9 - allows to enter one character from range a-z regardless of case or range 0-9;
S - alphabetical, a-zA-Z - same as A but without digits.

Any other character (if no translation supplied for) considered as static - when entering reaches it, caret just will be pushed forward to the next translatable. From the example above these are +, 7, -, so you are able to enter a phone number like +7-913-815-12-22 by entering only 9138151222

You could supply new translation by adding to the options an object like:

{
  '0': { pattern: /\d/ },
  '9': { pattern: /\d/, optional: true },
  '#': { pattern: /\d/, recursive: true },
  'A': { pattern: /[a-zA-Z0-9]/ },
  'S': { pattern: /[a-zA-Z]/ },
}

Here the key is a character to translate and value is a translation config. Config contains:

pattern - RegExp - pattern to restrict characters (allows entering only matched characters), required;
optional - bool - if set, this character will be allowed to skip, defaults to false;
recursive - bool - allows repeatable input, defaults to false;
fallback - string - replacement, if entered character doesn't match the pattern and fallback id defined, component will use its value in masked string, defaults to undefined;