v-mask

A Vue directive for formatting and restricting user input in input fields.

Import

To use the v-mask directive in your Vue application, follow the installation and import instructions in our Add Directive Guide.

API

Tokens

The v-mask directive utilizes a set of predefined tokens to define the input mask. These tokens and their corresponding patterns are:

const defaultTokens = {
  '#': { pattern: /[0-9]/ }, // Number
  'S': { pattern: /[a-zA-Z]/ }, // Alphabet with lower and uppercase
  'X': { pattern: /[a-zA-Z0-9]/ }, // Alphanumeric
  'A': { pattern: /[A-Z]/ }, // Uppercase alphabet
  'a': { pattern: /[a-z]/ } // Lowercase alphabet
}

Here's a breakdown of what each token allows:

• #: Allows any numeric character (0-9).
• S: Allows any alphabet character, both lowercase (a-z) and uppercase (A-Z).
• X: Allows any alphanumeric character, i.e., numbers (0-9) and alphabet characters (a-z, A-Z).
• A: Allows any uppercase alphabet character (A-Z).
• a: Allows any lowercase alphabet character (a-z).

You can use these tokens when defining your mask pattern to control the type of characters allowed at specific positions.

defineMaskOptions

To help you create more complex and type-safe mask configurations, we expose a utility function called defineMaskOptions. This function is particularly useful when you need to define advanced masking behaviors, such as custom tokens, number formatting, or post-processing logic, while ensuring your options object adheres to the expected structure and types.

Using defineMaskOptions provides autocompletion and type checking in your IDE, making it easier to define valid mask options and catch potential errors early.

import { defineMaskOptions } from '@mekari/pixel3'

const customMask = defineMaskOptions({
  mask: '##-AAA',
  tokens: {
    '#': { pattern: /[0-9]/ },
    'A': { pattern: /[A-Z]/, transform: (char: string) => char.toUpperCase() }
  },
  onUpdate: (detail) => {
    console.log('Masked:', detail.masked)
    console.log('Unmasked:', detail.unmasked)
  },
  postProcess: (val: string) => val ? `PREFIX-${val}` : ''
})

For more examples on using defineMaskOptions, see the Advance, Currencies, and Controlled examples below.

Usage

Basic

Advance

Currencies

With other components

Controlled