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

@im-open/text-mask-core

v5.1.3

Published

Core of https://github.com/im-open/text-mask

Downloads

23

Readme

Text Mask Core

This module contains the core functions that power Text Mask. Text Mask has wrappers for Angular1, Angular2, Ember, React and Vue which can be used directly.

However, Text Mask Core functions could be useful on their own. That's why they are published and documented here as a separate module.

Getting started

To download the script, use npm.

npm i text-mask-core --save

Include it

After installing with npm, you could possibly do something like this from your index.html:

<script src="./node_modules/text-mask-core/dist/textMaskCore.js"></script>

Including this file in your source code will expose the global object textMaskCore.

Or if you're using Node.js or a bundler such as webpack or Browserify, you can require textMaskCore as such:

var textMaskCore = require("text-mask-core");

How to use

textMaskCore exposes three functions:

  • createTextMaskInputElement
  • conformToMask
  • adjustCaretPosition

Overview

The general idea is to take user input, conform it to your desired mask using conformToMask, and then apply the output of conformToMask to the value of the HTML input element. Once you do that however, the caret position will be lost. You can then use adjustCaretPosition to restore the caret to its proper position.


API documentation

createTextMaskInputElement(config)

This function takes a configuration and returns an object with an update method. The update method is used to conform the raw value to the mask you provide in the config.

// the config requires a `mask` and a reference to an `input` element.
const textMaskConfig = { inputElement, mask };

// initialize text mask
const textMaskInputElement = createTextMaskInputElement(textMaskConfig);

// call `update` to conform the `inputElement.value` to the provided `mask`.
textMaskInputElement.update();

The textMaskConfig requires a mask and a reference to the inputElement. See the documentation here for more information on the properties that the textMaskConfig accepts.

The default use-case is for the textMaskConfig to be passed to the createTextMaskInputElement method when you initialize Text Mask. However, you can also pass the value and textMaskConfig to the update method.

const textMaskConfig = { inputElement, mask };

// initialize text mask without a config (or with a default config)
const textMaskInputElement = createTextMaskInputElement();

// call `update` with the raw value and config
textMaskInputElement.update(inputElement.value, textMaskConfig);

The update method should be called every time the inputElement.value changes.


conformToMask(rawValue, mask, config)

This function takes three arguments:

  • rawValue (string): the string value that you want to conform to the mask
  • mask (array or function): the mask to which you want the string to conform. You can find mask documentation here.
  • config (object): config object. See below for details

This function returns an object with a property conformedValue (string).

const results = conformToMask("5554833902", [
  "(",
  /[1-9]/,
  /\d/,
  /\d/,
  ")",
  " ",
  /\d/,
  /\d/,
  /\d/,
  "-",
  /\d/,
  /\d/,
  /\d/,
  /\d/,
]);

results.conformedValue; // '(555) 483-3902'

config

The config object takes the following values

  • guide (boolean) (defaults to true): this tells conformToMask whether you want the conformed string to contain a guide or no. The guide is basically the placeholder character and the mask hard characters. For example, with mask ['(', /[1-9]/, /\d/, /\d/, ')', ' ', /\d/, /\d/, /\d/, '-', /\d/, /\d/, /\d/, /\d/], input 123 with guide set to true would return (123) ___-____. With guide set to false, it would return (123) .

  • previousConformedValue (string) (required): this is the previous output of conformToMask. If you're calling conformToMask for the first time, you don't have to pass this value.

  • placeholderChar (string) (optional): for documentation on this key, see this section of the component documentation page.

const results = conformToMask("5554833902", [
  "(",
  /[1-9]/,
  /\d/,
  /\d/,
  ")",
  " ",
  /\d/,
  /\d/,
  /\d/,
  "-",
  /\d/,
  /\d/,
  /\d/,
  /\d/,
]);

results.conformedValue; // '(555) 483-3902'

Whenever the value of the input element changes, you can pass that value to conformToMask and it'll make sure that the string looks like the given mask. You can then set that conformed string as the new value of the input element.


adjustCaretPosition(argumentsObject)

When you set the value of the input element, you lose the position of the caret. This function helps you restore the position.

adjustCaretPosition takes the following object of arguments:

  • previousConformedValue (string): the string value of the input before the last time you set its value. If you're calling this function for the first time, you can pass an empty string.
  • conformedValue (string): the conformedValue returned from the last call to conformToMask
  • currentCaretPosition (integer): the position of the caret right before you called this function
  • rawValue (string): value of the input element
  • placeholderChar (string): placeholder character
  • placeholder (string): the generated placeholder
  • indexesOfPipedChars (array): an array of piped characters returned from the last call to the pipe function
  • caretTrapIndexes (array): an array of caret trap indexes

adjustCaretPosition will return an integer representing the index of where the caret should be moved to next.