hooks/input-masking

16 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

useMask hook overview

useMask attaches real-time input masking to any input element via a ref callback. It formats user input against a defined pattern and exposes both the masked display value and the raw unmasked value. For a ready-made input component, use MaskInput which wraps this hook with all standard input props.

Built-in mask tokens

The built-in mask tokens are: 9 for any single digit [0-9], a for any single letter [A-Za-z], A for any uppercase letter [A-Z], * for any alphanumeric character [A-Za-z0-9], and # for digit or sign [-+0-9].

Mask pattern optional segments

Append ? after the last required character to mark remaining slots as optional. For example, mask '(999) 999-9999? x9999' makes the extension optional.

Escaping mask tokens

Prefix a token character with a backslash to treat it as a literal. For example, \A makes A a literal character instead of an uppercase letter token.

useMask regex array format

For complex masks where built-in tokens are not enough, pass an array of string literals and RegExp objects to the mask option. This allows fine-grained control over individual digit restrictions, such as limiting the first digit of hours to 0-2.

UseMaskOptions interface

UseMaskOptions interface contains: mask (string | Array<string | RegExp>, required) for mask pattern; tokens (Record<string, RegExp>, optional) to override or extend default token map; modify ((value: string) => Partial<Pick<UseMaskOptions, 'mask' | 'tokens' | 'slotChar'>> | undefined, optional) called on each keystroke; transform ((char: string) => string, optional) to transform each character before validation; slotChar (string | null, optional, default '_') character displayed in unfilled slots; alwaysShowMask (boolean, optional, default false) to show pattern when empty and unfocused; showMaskOnFocus (boolean, optional, default true) to show mask placeholder on focus; autoClear (boolean, optional, default false) to clear value on blur when incomplete; invalid (boolean, optional) to set aria-invalid; onChangeRaw ((rawValue: string, maskedValue: string) => void, optional) called on every change; onComplete ((maskedValue: string, rawValue: string) => void, optional) called when all required slots filled.

UseMaskReturnValue interface

UseMaskReturnValue interface contains: ref (React.RefCallback<HTMLInputElement>) callback to attach to the input element; value (string) current masked display value; rawValue (string) current raw unmasked value; isComplete (boolean) whether all required mask slots are filled; reset (() => void) function to clear the input value and reset state.

formatMask utility function

formatMask(raw, options) applies a mask to a raw value string. Example: formatMask('1234567890', { mask: '(999) 999-9999' }) returns '(123) 456-7890'.

unformatMask utility function

unformatMask(masked, options) strips all mask literals from a masked value. Example: unformatMask('(123) 456-7890', { mask: '(999) 999-9999' }) returns '1234567890'.

isMaskComplete utility function

isMaskComplete(masked, options) checks if all required slots are filled. Example: isMaskComplete('(123) 456-7890', { mask: '(999) 999-9999' }) returns true.

generatePattern utility function

generatePattern(mode, options) generates a regex string for HTML pattern attribute.

useMask modify option for dynamic masks

Use the modify option to change the mask based on the current input value. The modify callback receives the current value and can return partial overrides for mask, tokens, or slotChar properties.

useMask transform option for character conversion

The transform option converts each character before validation. For example, using it to auto-uppercase input allows the A token to accept lowercase letters that are converted to uppercase.

useMask isComplete property

Use isComplete to check whether all required mask slots are filled, for example to control whether a submit button should be enabled.

useMask reset function

The reset function returned by useMask programmatically clears the input value and resets the hook state.

Export useMask types

The UseMaskOptions and UseMaskReturnValue types are exported from the @mantine/hooks package and can be imported as: import type { UseMaskOptions, UseMaskReturnValue } from '@mantine/hooks';

Give your agent this brain