Masked Input

Overview

Masked Input enforces a Mask pattern of digit / letter / literal tokens on every keystroke. On each input the engine’s createMaskedSelection bridge reads the proposed value and selection atomically; C# walks the mask and re-lands the caret in one call, so editing in the middle of the value is stable. It can be controlled (@bind-Value) or uncontrolled (DefaultValue), and degrades to a plain input if the engine is unavailable.

Anatomy

@using Navius.Primitives.Components.MaskedInput

<NaviusMaskedInput Mask="0000-0000-0000-0000" @bind-Value="_card" />

Root

The masked field. Renders an input. Value is two-way bindable.

Prop	Type	Default	Description
Mask	string	""	The mask pattern: 0 = digit, A = letter, * = alphanumeric, anything else is a fixed literal.
Value	string?	-	Controlled masked value. Pair with ValueChanged (@bind-Value).
ValueChanged	EventCallback<string>	-	Fires when the controlled value should change.
DefaultValue	string?	-	Initial value for uncontrolled use (masked or raw; normalized through the mask).
Placeholder	char?	-	The char shown for empty slots (e.g. _). null shows nothing (lazy skeleton).
Lazy	bool	true	true: trailing fixed tokens appear only as you reach them. false: eager.
Overwrite	bool	false	Reserved for type-over (replace) mode; accepted for parity, not yet wired to insertion.
Preprocessors	IReadOnlyList<Func<ElementState, ElementState>>?	-	Ordered pure transforms run on the proposed state before masking.
Postprocessors	IReadOnlyList<Func<ElementState, ElementState>>?	-	Ordered pure transforms run on the masked state after masking.
UnmaskedValueChanged	EventCallback<string>	-	The raw editable characters (placeholder-filled, no literals).
Disabled	bool	false	Disables the input.
Invalid	bool	false	Reflected as data-invalid for the skin; validation itself is the consumer’s concern.
Attributes	IDictionary<string, object>?	-	Forwarded to the rendered input (e.g. inputmode, aria-label).

Mask tokens

The Mask pattern is a string of these tokens; anything that is not a token is a fixed literal (rendered as you reach it under Lazy).

Token	Description
0	A required digit (0-9)
A	A required letter
*	A required alphanumeric character
(any other char)	A fixed literal, inserted automatically

Data attributes

Part	Attribute	Description
Root	data-navius-masked-input	Present on the input.
Root	data-empty	Present when no editable characters are entered.
Root	data-disabled	Present when disabled.
Root	data-invalid	Present when Invalid is set.

ARIA mechanism

Masked Input renders a plain <input> and wires no ARIA role of its own beyond aria-invalid="true", which reflects the Invalid prop; pair it with a Label (or splat an aria-label) and set an inputmode that fits the mask. It has no keyboard interactions beyond native text-input editing. This is covered by the Playwright browser test suite.