mother-mask

mother-mask

Lightweight input mask library for browsers. Zero runtime dependencies, TypeScript-first, ships ESM, CJS, and UMD.

Published as mother-mask on npm.

Live demo

Try it on StackBlitz →

Install

npm install mother-mask
# or
pnpm add mother-mask

Usage

bind(input, mask, options?)

Attach a mask to any input element — this is the main API.

• Idempotent — calling bind() again on the same element does nothing (the element is marked with data-masked).
• Returns a dispose function — call it to remove listeners and attributes so you can bind again later.
• Sets sensible defaults when missing: autocomplete, autocorrect, autocapitalize, spellcheck, and maxlength from the mask.

import { bind } from 'mother-mask'

const input = document.getElementById('phone') as HTMLInputElement

// Fixed mask
const dispose = bind(input, '(99) 99999-9999')

// Dynamic mask — picks the pattern from an ordered list (shortest → longest)
bind(input, ['(99) 9999-9999', '(99) 99999-9999'])

// Callback after paste or keyboard-driven changes
bind(input, '999.999.999-99', (value) => {
  console.log(value) // e.g. "123.456.789-01"
})

// Or options object (same as callback for a single `onChange`)
bind(input, '999.999.999-99', { onChange: (value) => console.log(value) })

// Later: allow rebinding
dispose()

Pattern syntax

Character	Matches
9	Digit (0–9)
Z	Letter (a–z, A–Z)
A	Alphanumeric (digit or letter)
Anything else	Literal — inserted as the user fills slots

Array masks

Pass an ordered array shortest → longest for variable-length inputs. The active mask is chosen from the count of alphanumeric “data” characters in the current value, so it works for both progressively masked input and fast typing.

bind(input, ['(99) 9999-9999', '(99) 99999-9999'])
bind(input, ['999.999.999-99', 'AA.AAA.AAA/AAAA-99'])

UMD / CDN

<script src="https://unpkg.com/mother-mask/dist/mother-mask.umd.js"></script>
<script>
  const dispose = MotherMask.bind(document.getElementById('cpf'), '999.999.999-99')
</script>

The global name is MotherMask.

API reference

bind (primary)

Signature	bind(input, mask, options?)
Returns	() => void — call to remove listeners and attributes so the input can be bound again
Third argument	{ onChange?: (value: string) => void }, or a legacy (value) => void callback

Other exports

Export	Description
buildMask(value, mask, caret?)	Build a Mask instance (array mask is resolved to one string first).
getMaxLength(mask)	Maximum string length for the mask (for array masks, the longest pattern).
applyMask(value, mask, inputCaret?)	Low-level: apply a single mask string; returns { value, caret }.

Mask class

buildMask returns a Mask for advanced use. The instance applies the pattern and keeps a caret position aligned with the masked output (see TypeScript definitions in the package).

Types

type MaskPattern = string | string[]

interface MaskResult {
  readonly value: string
  readonly caret: number
}

interface BindOptions {
  onChange?: (value: string) => void
}

MaskPattern, MaskResult, and BindOptions are exported as types.

License

MIT — Danilo Celestino de Castro