maska/docs/v3/options.md

Options

There are two main components that you can customize: the Mask class and the MaskInput class. You typically work directly with the latter, but since MaskInput options extend Mask options, you can configure both using a single object.

Mask options

To set options for a Mask class you can pass an object when creating the class:

new Mask({ mask: "#-#", eager: true, number: { locale: 'de' }})

Options passed in this way will be used as default values and can be overridden by data-maska- attributes of a given input element.

Description

Option / data-attribute	Default	Description
mask data-maska	—	Mask to apply (string, array of strings or function). If you pass an empty string or null it will disable a mask
tokens data-maska-tokens	—	Custom tokens object. See tokens page
tokensReplace data-maska-tokens-replace	false	If custom tokens should replace default tokens (if not set, they will merge)
eager data-maska-eager	false	Eager mode will show static characters before you type them, e.g. when you type 1, eager mask #-# will show 1- and non-eager will show 1
reversed data-maska-reversed	false	In reversed mode mask will grow backwards, e.g. for numbers
number.locale data-maska-number-locale	en	Locale for number mode. Determine the national format for the number
number.fraction data-maska-number-fraction	0	Fraction digits for the number (0 allows only integer numbers)
number.unsigned data-maska-number-unsigned	false	Unsigned mode for the number: if you want to accept only positive numbers

Types

interface MaskOptions {
  mask?: MaskType
  tokens?: MaskTokens
  tokensReplace?: boolean
  eager?: boolean
  reversed?: boolean
  number?: MaskNumber
}

type MaskType = string | string[] | ((input: string) => string) | null

interface MaskToken {
  pattern: RegExp
  multiple?: boolean
  optional?: boolean
  repeated?: boolean
  transform?: (char: string) => string
}

type MaskTokens = Record<string, MaskToken>

interface MaskNumber {
  locale?: string
  fraction?: number
  unsigned?: boolean
}

MaskInput options

MaskInput options can only be set when creating a class, as they are too complex to use data-maska- attributes for them. Along with MaskInput options you can also pass any Mask class options (or set them using data-maska- attributes):

new MaskInput("input", {
  onMaska: (detail) => console.log(detail.completed)
  mask: "#-#",
  reversed: true,
})

Description

Option	Description
onMaska	Сallback (event analog), called after every mask processing
preProcess	Hook called before mask processing
postProcess	Hook called after mask processing

Types

interface MaskInputOptions extends MaskOptions {
  onMaska?: (detail: MaskaDetail) => void
  preProcess?: (value: string) => string
  postProcess?: (value: string) => string
}

interface MaskaDetail {
  masked: string
  unmasked: string
  completed: boolean
}

!> Please note that data- attributes only accept strings, so if you need to set complex values such as functions (e.g. for hooks) you cannot use data-maska- attributes for that.

?> Examples on this page use vanilla version of Maska. The framework specific versions have the same options, but should be passed in a different way: for example, as a directive value.

Number mask

Number mode makes it easy to format numbers according to the selected locale.

You can enable the number mode using number option or data-maska-number- attributes. In that case you don't need to set mask or any other options. All number options are optional:

By data-attributes

<!-- Minimal example -->
<input data-maska-number>

<!-- Full example -->
<input
  data-maska-number-locale="ru"
  data-maska-number-fraction="2"
  data-maska-number-unsigned
>

By option

// minimal example
new MaskInput("input", {
  number: {}
})

// full example
new MaskInput("input", {
  number: {
    locale: "ru",
    fraction: 2,
    unsigned: true
  }
})

?> Under the hood Maska uses the Intl.NumberFormat for number formatting. Therefore, the maximum number that can be formatted should be less than 9007199254740991.

!> For some locales, such as de or br, which use a dot . as a thousand separator, you should manually format the initial value before passing it. For more information, please see issue #225.

Dynamic masks

Pass mask as array or function to make it dynamic:

• With array a suitable mask will be chosen by length (smallest first)
• With function you can select mask with custom logic using value

new MaskInput("input", {
  mask: (value: string) => value.startsWith('1') ? '#-#' : '##-##'
})