useMaskedInput

v0.0.14testeddemo

Headless input masking. Returns a bind object to spread onto an <input>/<textarea> (<input v-bind="bind">) — it carries the template ref and the event handlers, so there is no separate ref wiring. Conforms the value on every keystroke (insert/delete/paste/IME) with a correct caret, and exposes the masked/unmasked views plus a complete signal.

Source Tests

Examples

const phone = useMaskedInput({ mask: '+1 (###) ###-####' });
// <input v-bind="phone.bind">
// phone.unmasked.value → '1234567890'

const amount = useMaskedInput({
  mask: maskNumberOptions({ thousandSeparator: ',', precision: 2, prefix: '$' }),
  onAccept: ({ unmasked }) => save(unmasked),
});

Demo

Loading demo…

Signature

export function useMaskedInput(options: UseMaskedInputOptions): UseMaskedInputReturn{ ... }

Parameters

Parameter	Type	Default	Description
`options`	`UseMaskedInputOptions`	—	The mask and behavior

Returns

UseMaskedInputReturnbind, masked, unmasked, complete, ensureFitsMask, setValue

Property	Type	Default	Description
`masked`	`ShallowRef<string>`	—	The conformed, displayed value (kept in sync with the element).
`unmasked`	`Readonly<ShallowRef<string>>`	—	The raw value with fixed mask characters (and preset separators) stripped.
`complete`	`ComputedRef<boolean>`	—	Whether `masked` fully satisfies the mask.
`bind`	`MaskInputBindings`	—	Spread onto the input element: `<input v-bind="bind">`.
`ensureFitsMask`	`() => void`	—	Re-conform the element's current value (e.g. after a programmatic set).
`setValue`	`(value: string) => void`	—	Set the value programmatically — treated as raw input and conformed.

Related Types

UseMaskedInputOptions

Options for useMaskedInput.

interface UseMaskedInputOptions

Property	Type	Default	Description
`mask`	`MaybeRefOrGetter<MaskOptionInput>`	—	The mask source: a full options object, a bare mask expression, or a template string (e.g. `'+1 (###) ###-####'`). May be reactive.
`overwriteMode`?	`OverwriteMode`	`'shift'`	Insert vs overwrite behavior under a collapsed caret. Overrides any `overwriteMode` carried by the resolved mask options.
`initialCalibration`?	`boolean`	`true`	Conform the element's current value once, as soon as it is bound.
`onAccept`?	`(state: { masked: string; unmasked: string }) => void`	—	Called after each accepted change with both views of the value. The one-liner bridge for feeding the raw value into a form.

MaskInputBindings

Bindings to spread onto the <input>/<textarea> via v-bind. Contains the template-ref callback that attaches the element plus the event handlers that drive masking — no separate ref wiring needed.

interface MaskInputBindings

Property	Type	Default	Description
`ref`	`(element: Element \| null) => void`	—	Template-ref callback — attaches the element (`v-bind` sets it for you).
`onInput`	`() => void`	—	`input` handler — re-conforms after exotic/composition input types.
`onBeforeinput`	`(event: InputEvent) => void`	—	`beforeinput` handler — the insert/delete masking pipeline.
`onCompositionend`	`() => void`	—	`compositionend` handler — re-conforms after IME composition.

UseMaskedInputReturn

The reactive API returned by useMaskedInput.

interface UseMaskedInputReturn

Property	Type	Default	Description
`masked`	`ShallowRef<string>`	—	The conformed, displayed value (kept in sync with the element).
`unmasked`	`Readonly<ShallowRef<string>>`	—	The raw value with fixed mask characters (and preset separators) stripped.
`complete`	`ComputedRef<boolean>`	—	Whether `masked` fully satisfies the mask.
`bind`	`MaskInputBindings`	—	Spread onto the input element: `<input v-bind="bind">`.
`ensureFitsMask`	`() => void`	—	Re-conform the element's current value (e.g. after a programmatic set).
`setValue`	`(value: string) => void`	—	Set the value programmatically — treated as raw input and conformed.