Maska

Maska is a zero-dependency input mask library that provides three main ways to apply masks:

1. Mask: A class used for core mask processing. It can be used to mask any arbitrary string, not just input elements.
2. MaskInput: A class specifically designed to handle user interaction with <input> elements.
3. Directives: Framework-specific integrations for easy use:
   • Vue: Use the vMaska directive.
   • Alpine.js: Use the xMaska directive.
   • Svelte: Use the maska action.

Maska provides a vanilla JavaScript core along with official integrations for several frameworks. Key features include:

• Framework Integrations: Vue 2, Vue 3, Alpine.js, and Svelte.
• Customization: Support for custom tokens using modifiers, transform functions, and hooks.
• Specialized Modes: Number mask mode for currency/money formatting, and support for dynamic, reversed, and eager masks.
• Compatibility: Works with native HTML inputs and custom input components.

Maska provides three default tokens for common character types. You can use these tokens directly in your mask string. To use the literal character instead of the token, escape it with an exclamation mark (!).

Default Tokens:

• #: Digits (/[0-9]/)
• @: Letters (/[a-zA-Z]/)
• *: Letters & digits (/[a-zA-Z0-9]/)

Example: Using !# will render the literal # character instead of matching a digit.

{
  '#': { pattern: /[0-9]/ },       // digits
  '@': { pattern: /[a-zA-Z]/ },    // letters
  '*': { pattern: /[a-zA-Z0-9]/ }, // letters & digits
}

Modifiers allow you to change how a token behaves during input. They can be applied in the Simple form of data-maska-tokens using the syntax T:P:M.

Examples:

• Optional (IP address): Mask #00.#00.#00.#00 using 0:[0-9]:optional.
• Multiple (Cardholder Name): Mask A A using A:[A-Z]:multiple.
• Repeated (Money): Mask 9 99#,## using 9:[0-9]:repeated.

{
  0: { pattern: /[0-9]/, optional: true },
  9: { pattern: /[0-9]/, repeated: true },
}

Maska consists of three main components designed for different use cases:

• Mask class: Used to mask string values programmatically.
• MaskInput class: Used to apply Mask processing to <input> elements in Vanilla JS environments.
• vMaska directive: A Vue directive to simplify using the library within Vue components.

In Maska v3, eager: true mode has changed how entered characters interact with static mask symbols.

In v2, entered characters appeared after the static mask characters. In v3, entered characters are treated as if they occupy the positions of the static symbols themselves.

// v2 behavior
const mask = new Mask({ mask: '1##', eager: true })
mask.masked('1') // -> 11
mask.masked('12') // -> 112
mask.masked('2') // -> 12

// v3 behavior
const mask = new Mask({ mask: '1##', eager: true })
mask.masked('1') // -> 1
mask.masked('12') // -> 12
mask.masked('2') // -> 12

When using an array of masks (dynamic masks), the definition of a 'completed' mask has changed between versions.

• v2: A dynamic mask is considered completed only when it matches the longest mask in the array.
• v3: A dynamic mask is considered completed as soon as it matches the first mask in the array that fits the input.

Include the Maska Vue build from CDN and register the vMaska directive in your Vue application.

<script src="https://cdn.jsdelivr.net/npm/maska@3/dist/cdn/vue.js"></script>
<script>
  const { vMaska } = Maska

  Vue.createApp({ directives: { maska: vMaska }}).mount('#app')
</script>

To use Maska in Nuxt 3, create a plugin file in your plugins folder (e.g., plugins/maska.ts) to register the directive globally.

import { vMaska } from "maska/vue"

export default defineNuxtPlugin((nuxtApp) => {
  nuxtApp.vueApp.directive("maska", vMaska)
})

In Vue, use the v-maska directive on your input element. You can specify the mask pattern using the data-maska attribute and listen for the @maska event.

<input v-maska data-maska="#-#" @maska="onMaska" />

You can add custom tokens to an input using the data-maska-tokens attribute. There are two supported formats:

1. JSON form: A valid JSON string (supporting single or double quotes) where the pattern is a string without delimiters.
2. Simple form: A string using the format T:P:M|... where:
   • T is the token character.
   • P is the pattern in string form.
   • M is an optional modifier.
   • | is the separator for multiple tokens.

Note: You cannot define a transform function using the data-maska-tokens attribute; use the tokens option for that.