API reference

bind (primary)#

Signature	`bind(input, mask, options?)`
Returns	`() => void` — removes listeners and attributes so the input can be bound again
Third argument	`BindOptions`: pattern options, `onChange`, and the input attributes `autocomplete`, `autocorrect`, `autocapitalize`, and `spellcheck`; or a `(value) => void` callback

Other exports#

Export	Description
`buildMask(value, mask, caret?, options?)`	Build a `Mask` instance with the supplied pattern and options. Call `.process()` for the value, then read `.caret`.
`getMaxLength(mask, options?)`	Formatted UTF-16 upper bound, including literals; up to two units per custom-token slot, and a quantified run counted at its maximum — never the length of the pattern source. `Infinity` with a resolver.
`applyMask(value, mask, inputCaret?, options?)`	Apply a pattern string or ordered array with all pattern options; returns `{ value, caret }`.
`process(value, mask, options?)`	Apply a mask pattern to a raw value, returning just the masked string.
`new Mask(value, mask, caret?, options?)`	Low-level processor with `.process()` and `.caret`.

Pure formatting#

import { applyMask, process, processDecimal } from 'mother-mask'

process('12345678901', '999.999.999-99') // '123.456.789-01'
applyMask('25122025', '99/99/9999', 8) // { value: '25/12/2025', caret: 10 }
processDecimal('1234.567') // '1,234.567'
processDecimal('7.3', { numberPlaces: 2, decimalPlaces: 2 }) // '07.30'

Optional caret arguments default to 0. Input and output carets use UTF-16 offsets. Pure helpers do not track edit history or DOM events; binding-specific deletion and composition behavior requires bind() or bindDecimal().

bindDecimal#

Signature	`bindDecimal(input, options?)`
Returns	`() => void` — removes listeners and attributes so the input can be bound again
Second argument	`BindDecimalOptions` (decimal options, `onChange`, and the shared input attributes), or a `(value, numericValue) => void` callback

Other decimal exports#

Export	Description
`applyDecimalMask(value, inputCaret?, options?)`	Low-level: format a raw/already-masked value; returns `{ value, caret }`.
`processDecimal(value, options?)`	Format a string in the configured locale, returning just the masked string.
`unmaskDecimal(value, options?)`	Parse a raw or masked decimal string back into a JS `number` (`0` if it has no digits).
`formatDecimalValue(value, options?)`	Format a plain JS `number` into its masked display string — useful to pre-populate an input.

Types#

type MaskPattern = string | string[]

interface MaskResult {
  readonly value: string
  readonly caret: number // UTF-16 offset
}

type TokenMatcher = RegExp | ((char: string) => boolean)
interface MaskTokenDefinition {
  match: TokenMatcher
  transform?: (char: string) => string // exactly one code point
}
type MaskTokens = Record<string, TokenMatcher | MaskTokenDefinition>
type MaskResolver = (value: string) => MaskPattern

interface ApplyMaskOptions {
  segmented?: boolean // hard field boundaries for static masks — default true
  eager?: boolean     // reveal upcoming literals — default true
  tokens?: MaskTokens
  resolveMask?: MaskResolver
}

interface BindInputAttributes {
  autocomplete?: HTMLInputElement['autocomplete'] // default 'off'
  autocorrect?: 'on' | 'off'                      // default 'off'
  autocapitalize?: 'on' | 'off' | 'none' | 'sentences' | 'words' | 'characters' // default 'off'
  spellcheck?: boolean                             // default false
}

interface BindOptions extends ApplyMaskOptions, BindInputAttributes {
  onChange?: (value: string) => void
}

interface DecimalMaskOptions {
  decimalPlaces?: number      // unset: optional, unlimited fraction
  numberPlaces?: number       // unset: unlimited integer part
  segmented?: boolean         // group into thousands — default true
  separator?: string          // thousands separator — default ','
  decimalSeparator?: string   // default '.'
  prefix?: string             // default ''
  suffix?: string             // default ''
  allowNegative?: boolean     // default false
}

interface BindDecimalOptions extends DecimalMaskOptions, BindInputAttributes {
  onChange?: (value: string, numericValue: number) => void
}