useMaskedField

v0.0.14testeddemo

A masked form field: fuses useField with useMaskedInput so a formatted value is shown while the form stores the raw value (validation, dirty/touched, schema, and submit all read raw). Returns a single bind object to spread onto the input — it merges the field's name/onBlur/aria-invalid with the mask bindings (ref + handlers). Purely additive — it composes the existing form composables without modifying them.

Source Tests

Example

const { bind, errorMessage } = useMaskedField('phone', { mask: '+1 (###) ###-####' });
// <input v-bind="bind">  — the form stores the raw digits

Demo

Loading demo…

Signature

export function useMaskedField<T = string>(
  path: MaybeRefOrGetter<string>,
  options: UseMaskedFieldOptions<T>,
): UseMaskedFieldReturn<T>{ ... }

Type Parameters

T= string

Parameters

Parameter	Type	Default	Description
`path`	`MaybeRefOrGetter<string>`	—	The dotted field path
`options`	`UseMaskedFieldOptions<T>`	—	The mask plus any `useField` options

Returns

UseMaskedFieldReturn<T>The field API plus display, unmasked, complete, bind

Property	Type	Default	Description
`display`	`ShallowRef<string>`	—	The masked display text (read-only; the input shows it via `bind`).
`unmasked`	`Readonly<ShallowRef<string>>`	—	The raw unmasked value (mirrors what is written to the form by default).
`complete`	`ComputedRef<boolean>`	—	Whether the mask is fully satisfied.
`bind`	`ComputedRef<Record<string, unknown>>`	—	Spread onto the input (`<input v-bind="bind">`): merges the field's `name`/`onBlur`/`aria-invalid` with the mask bindings (ref + input handlers).
`value`	`Ref<T>`	—	The field's writable value (bound to the form path, or local in standalone).
`errors`	`ComputedRef<string[]>`	—	The field's error messages.
`errorMessage`	`ComputedRef<string \| undefined>`	—	The field's first error message, if any.
`meta`	`FieldMeta`	—	Grouped reactive meta for the field.
`handleBlur`	`(event?: Event) => void`	—	Blur handler — marks touched and (re)validates per trigger.
`handleChange`	`(value: T, shouldValidate?: boolean) => void`	—	Set the value and optionally validate.
`handleInput`	`(event: Event) => void`	—	`input`/`change` DOM handler for native elements.
`setValue`	`(value: T) => void`	—	Set the field value programmatically.
`setTouched`	`(touched?: boolean) => void`	—	Mark the field touched/untouched.
`setErrors`	`(message: string \| string[] \| null) => void`	—	Set or clear (with `null`) the field's errors.
`validate`	`() => Promise<FieldValidationResultDetail>`	—	Validate just this field.
`reset`	`() => void`	—	Reset the field to its initial value.
`attrs`	`ComputedRef<FieldBindingProps>`	—	Props to spread on the field element (`v-bind="attrs"`).

Related Types

UseMaskedFieldOptions

Options for useMaskedField. Extends UseFieldOptions with the mask configuration.

interface UseMaskedFieldOptions<T = string> extends UseFieldOptions<T>

Property	Type	Default	Description
`mask`	`MaybeRefOrGetter<MaskOptionInput>`	—	The mask source: a full options object, a bare mask, or a template string. May be reactive.
`modelValue`?	`'masked' \| 'unmasked'`	`'unmasked'`	Which view of the value is written into the form (and submitted): - `unmasked` — the raw value (recommended: schemas validate clean data); - `masked` — the formatted display string.
`overwriteMode`?	`OverwriteMode`	`'shift'`	Insert vs overwrite behavior under a collapsed caret.

UseMaskedFieldReturn

The reactive API returned by useMaskedField: everything from useField plus the masking views and a single bind object.

interface UseMaskedFieldReturn<T = string> extends UseFieldReturn<T>

Property	Type	Default	Description
`display`	`ShallowRef<string>`	—	The masked display text (read-only; the input shows it via `bind`).
`unmasked`	`Readonly<ShallowRef<string>>`	—	The raw unmasked value (mirrors what is written to the form by default).
`complete`	`ComputedRef<boolean>`	—	Whether the mask is fully satisfied.
`bind`	`ComputedRef<Record<string, unknown>>`	—	Spread onto the input (`<input v-bind="bind">`): merges the field's `name`/`onBlur`/`aria-invalid` with the mask bindings (ref + input handlers).