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

rxmask

v1.4.15

Published

Simple, but advanced mask parser for html input or parsing provided string directly

Downloads

29

Readme

rxmask.js

minzipped size downloads type definitions

Easy to install and use advanced mask package.

Demo

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 from src/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 with input 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 include placeholderSymbol, otherwise user will not be able to type any characters.
  • rxmask - regex mask (if rxmask 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 any number including Infinity to show whole mask).
  • trailing - if trailing is true, show trailing mask symbols. Example: if with mask ***--**-** user types 123, user will get 123--, but if he removes symbol 4 from 123--4, he will get just 123 without -. If trailing is disabled, regardless of user actions value 123 will always result in just 123.

These are class only options:

  • value - assign to it value you want to parse
  • cursorPos - you can assign to it cursor position value (in case of <input> it's selectionStart property). After parseMask() 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 to Parser yourself. It will parse the mask and update output and finalCursorPos values.
  • onInput() method - you should call this method when you provided Parser class with input object. It will get all properties from provided input, call parseMask() and update output and finalCursorPos values. Grab this values after you called parseMask()
  • output - parsed value that has applied mask to it. This value is the correct field to use as parsed mask value.
  • parsedValue - parsed value before mask was applied. This value is the correct parsed value without mask.
  • finalCursorPos - modified cursorPos. 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