rxmask
v1.4.15
Published
Simple, but advanced mask parser for html input or parsing provided string directly
Downloads
125
Maintainers
Readme
rxmask.js
Easy to install and use advanced mask package.
Playground: https://rxmask.kmesh.dev/.
Features
- Both module and simple HTML script
- Flexible - allows to change mask, placeholder symbol format, show or hide unfilled mask (or even part of it) and more
- Allows to use same characters that are present in mask
- Allows to specify format for every character
- Detailed input error log
- Robust (test coverage with Cypress)
- No dependencies
If you want to check my other projects, you can visit my portfolio: https://portfolio.kmesh.dev/
Table of contents
Example
You can see this package in action in playground: https://rxmask.kmesh.dev/, or you can go to example/example.html
in the project to see how this package works in plain HTML file.
You can view source code in ./src folder
: rxmask.ts
for typescript or rxmask.js
for javascript.
Installation
Use it in script tag
It will work for simple plain html files.
- Download
rxmask.min.js
file fromsrc/rxmask.min.js
(minified and polyfilled). - Add downloaded script in the head of the document.
Example:
<head>
<script src="../src/rxmask.min.js"></script>
</head>
<body>
<input class="rxmask" mask="***-**-**" placeholderSymbol="*" allowedCharacters="[0-9]"/>
</body>
You should include class="rxmask"
in your input - it's the only way for script to automatically parse DOM tree for inputs to be applied mask to. Also you can add any of the Options in the first section to the input as properties. See example.html
for more some examples.
You can also use unminified rxmask.js
file, though it's recommended to use minified due to far smaller size and superior browser support. If you still want to use unminified version (I used it in example for easier debugging), replace <script>
tag with this:
<script type="module" src="../src/rxmask.js"></script>
Use it for existing input
object (<HTMLTextAreaElement>
or <HTMLInputElement>
type)
npm i rxmask
- Import
Parser
class (it has default export). - Create instance of
Parser
class and provide it with options alongside withinput
object itself (it should accept basic, React or any other input as long as it's derived from<HTMLTextAreaElement>
or<HTMLInputElement>
type). - Add
parser.onInput
method to event of your input that is triggered on every input change.
Example:
import rxmask from 'rxmask';
const input = document.getElementsByClassName('rxmask')[0];
const parser = new rxmask({}, input);
input.oninput = () => parser.onInput();
Use it to parse raw string value
It's useful if you want to just parse value according to any mask, detached from any actual input element.
npm i rxmask
- Import
Parser
class (it has default export). - Create instance of
Parser
class and provide it with options (it's recommended to provide it at least with input value (and also cursor position if you need to calculate cursor position). - Call
parseMask()
to process input value.
Example:
import rxmask from 'rxmask';
const parser = new rxmask({ mask: '***-**-**', placeholderSymbol: '*' });
// You can provide value as an option, but it's recommended to add value separately every time before calling parseMask()
parser.options.value = '1234';
parser.parseMask();
// parser.output will have value of '123-4', finalCursorPos will have value of 5
Note that under the hood class stores previous value, so if you want to just parse string once, you need to reinitialize class every time so it will assume that previous value was empty string (this is subject to change).
Options
These options can be provided both to Parser
class itself (through options or property assignment) and as <input>
tag properties (note that if you are using options in <input>
tag, you should add data-
before any option, like data-maxMaskLength
):
mask
- mask, should includeplaceholderSymbol
, otherwise user will not be able to type any characters.rxmask
- regex mask (ifrxmask
is present,mask
will be ignored), characters in square brackets will be parsed as characters for user input, any other character will be parsed as mask symbol.placeholderSymbol
- symbol, that specifies character that will be replaced in mask with user input.allowedCharacters
- characters allowed to be used in this input. If this option is present, all other characters will be ignored when user types them.maxMaskLength
- show whole mask, part of it or not show it at all (can be anynumber
includingInfinity
to show whole mask).trailing
- if trailing istrue
, show trailing mask symbols. Example: if with mask***--**-**
user types123
, user will get123--
, but if he removes symbol4
from123--4
, he will get just123
without-
. If trailing is disabled, regardless of user actions value123
will always result in just123
.
These are class only options:
value
- assign to it value you want to parsecursorPos
- you can assign to it cursor position value (in case of<input>
it'sselectionStart
property). AfterparseMask()
was called,finalCursorPos
will be updated with appropriate value.
Also class has some important methods and properties:
parseMask()
method - you should call this method when you assigned all required parameters toParser
yourself. It will parse the mask and updateoutput
andfinalCursorPos
values.onInput()
method - you should call this method when you providedParser
class withinput
object. It will get all properties from providedinput
, callparseMask()
and updateoutput
andfinalCursorPos
values. Grab this values after you calledparseMask()
output
- parsedvalue
that has applied mask to it. This value is the correct field to use as parsed mask value.parsedValue
- parsedvalue
before mask was applied. This value is the correct parsed value without mask.finalCursorPos
- modifiedcursorPos
. This value is the correct cursor position to use for your input.errors
- array with errors on input. If no errors were made, this array is empty. If some errors were made, this array contains objects with wrong symbol, its position and error type.
Notes
- Typescript support (types file) is provided with package.
- NOT Unicode friendly (or any character that is represented by more than one UTF-16 code unit for that matter) - planned feature
Testing
I use Live Server extension for VSCode for easier testing.
- Launch Live Server for example/example.html (default address is
http://127.0.0.1:5500/example/example.html
) npm test
to launch Cypress