navius

Components / Masked Input

Masked Input

A caret-stable masked text input: a pattern of digit / letter / literal tokens is enforced on every keystroke without the caret ever jumping to the end.

Value: (415) 555-0132

razor
<NaviusMaskedInput Mask="(000) 000-0000" Placeholder="@('_')"
                  @bind-Value="_phone" inputmode="tel"
                  class="h-10 w-56 rounded-md border px-3 font-mono" />

@code { private string? _phone = "(415) 555-0132"; }

Features

  • On each input the engine's createMaskedSelection bridge reads the proposed value + selection atomically; C# walks the mask and re-lands the caret in one call, so editing in the middle is stable.
  • A Placeholder char fills empty slots (or shows nothing for a lazy skeleton); Lazy reveals trailing literals only as you reach them.
  • Optional pure Preprocessors / Postprocessors transform the state before / after masking; UnmaskedValueChanged exposes the raw editable characters.
  • Controlled via @bind-Value, uncontrolled via DefaultValue; degrades to a plain input if the engine is unavailable.

Installation

Install the brain, or copy just this primitive in with the CLI.

Terminal bash
navius add masked-input

Anatomy

A single input.

razor
@using Navius.Primitives.Components.MaskedInput

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

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).

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

API Reference

NaviusMaskedInput

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

Prop Type Default
Mask string ""
Value string? -
ValueChanged EventCallback<string> -
DefaultValue string? -
Placeholder char? -
Lazy bool true
Overwrite bool false
Preprocessors IReadOnlyList<Func<ElementState, ElementState>>? -
Postprocessors IReadOnlyList<Func<ElementState, ElementState>>? -
UnmaskedValueChanged EventCallback<string> -
Disabled bool false
Invalid bool false
…attributes IDictionary<string, object>? -

Data attributes

Data attribute Values
[data-navius-masked-input] Present on the input
[data-empty] Present when no editable characters are entered
[data-disabled] Present when disabled
[data-invalid] Present when Invalid is set

Accessibility

A plain <input>: pair it with a Label (or splat an aria-label) and set an inputmode that fits the mask. Invalid reflects as data-invalid for the skin; validation itself is the consumer's concern.