This is the v1.1 documentation. The current version is v2.0. Upgrade guide

Custom mask

When presets are not enough, use your own mask string and MaskOptions fields.

Syntax

Special tokens in the mask string:

Token	Meaning
`9`	Digit (0–9)
`a` / `A`	Letter (a–z). Use `transform` for case
`*`	Any character
Other	Literal separator ( , `/`, `(`, `)`…)

Form value: -

Display: -

const form = useForm({ defaultValues: { code: "" } })
 
const { code } = useViraMask({
  form,
  schema: {
    code: {
      mask: "aaa-999",
      transform: "uppercase",
    },
  },
})
 
const { rawValue, ...inputProps } = code
 
<input {...inputProps} placeholder="ABC-123" />

MaskOptions

Commonly used fields:

mask: pattern string
transform: uppercase | lowercase
allowedChars / forbiddenChars
displayPrefix: shown but not written to raw value (e.g. TR on IBAN)
currency, dateFormat, alphaFormat, usernameFormat
type, inputMode, autoComplete
preset: override on top of a preset

resolveMask

For dynamic masks, resolveMask(value, allValues, schema) returns a new mask string (or undefined). Card (Amex) and CVV presets use this: they update the mask based on sibling fields.

{
  mask: "9999 9999 9999 9999",
  resolveMask: (value) => {
    const digits = value.replace(/\D/g, "")
    if (digits.startsWith("34") || digits.startsWith("37")) {
      return "9999 999999 99999" // Amex
    }
    return undefined
  },
}