useMask
Mask
stable
Reactive input mask engine. Keeps a masked display string, an unmasked raw value, a validity flag, and a completion flag in sync with a source value and a polymorphic mask spec. Accepts both plain values and refs so it integrates directly with props.modelValue and props.mask.
API
Signature
Full TypeScript signature sourced from the composable file.
Consumed interfaces
IMaskOptions
IResolvedMaskConfig
API
Parameters
Input parameters accepted by this composable.
- modelValuerequiredMaybeRef<string | null | undefined>
- The raw input value to format. Accepts a plain string or a reactive ref. When it changes the mask is reapplied.
- maskrequiredMaybeRef<TMask | undefined>
- Mask spec — a pattern string (e.g. "##/##/####"), a named preset, or a custom config object. When it changes the current value is reformatted.
API
Return values
Properties and methods exposed by the composable return object.
- masked
- The formatted display string (e.g. "12/31/2024"). Bind to the input value displayed to the user.
- unmasked
- The raw digits/characters with mask literals stripped (e.g. "12312024"). Use this as the actual model value.
- isValid
- True when the unmasked value satisfies the mask pattern requirements (complete when required, passes regex validator when present).
- complete
- True when every placeholder slot in the mask pattern has been filled.
- setRaw
- Imperatively re-format an external raw value (e.g. after a paste event or external data sync). Returns the new unmasked value.
- config
- The currently resolved mask configuration (pattern array, validator, required flag). Null when no mask is active.
Usage
Examples
Ready-to-paste usage snippets.
Phone number mask
Date mask with reactive model