Input mask

Problem Context

• The field value has known character positions, group lengths, literal separators, or check digits.
• Users often copy the value from a document, card, label, shipment record, serial plate, or system-generated code.
• The grouped display reduces transcription errors and matches the user's source material.
• The product can define whether separators are stored, displayed only, copied, or stripped before backend validation.
• Valid exceptions, localization, alternate lengths, or picker-based entry have been checked before choosing a mask.

Selection Rules

• Choose input mask when the value has a stable, narrow structure with predictable character classes and grouping.
• Use text input when users may need to enter values outside one fixed structure, such as company names, freeform identifiers, or international contact details.
• Use inline validation when normal typing should remain unconstrained and the system can explain a format error after blur or submit.
• Use autocomplete when the typed value should resolve to an existing record instead of merely being shaped into a format.
• Use prefix/suffix when a constant symbol, unit, currency, or domain is separate from the user's typed value.
• Use a date picker, time picker, or domain-specific picker when the picker owns entry and masks would conflict with it.
• Do not mask emails, broad phone-number formats, addresses, names, or values with common legitimate exceptions.
• Keep hint text visible for complex formats; do not rely on placeholder mask characters alone.
• Support paste from both formatted and unformatted values.
• State or reveal whether literals are included in copied and submitted values.

Required States

• Empty untouched state with label and visible format example.
• Focused state that reveals grouping or mask affordance without replacing the label.
• Partially entered state with incomplete groups and stable cursor behavior.
• Pasted unformatted value normalized into the mask.
• Pasted formatted value accepted without duplicating separators.
• Invalid character attempted state with a non-blocking explanation or ignored-character status.
• Incomplete required value error after submit.
• Complete formatted display state with canonical stored value visible or inspectable.
• Deletion or correction state where placeholders do not shift remaining characters unpredictably.
• Exception or unsupported-format state with a fallback path.

Interaction Contract

• Typing valid characters fills the next available mask slot and inserts literal separators automatically.
• Typing invalid characters either ignores them with a clear status or leaves the value unchanged without corrupting existing characters.
• Pasting formatted or unformatted content normalizes into the same display value.
• Deleting, selecting, replacing, undoing, and correcting middle groups remain predictable.
• Submitting an incomplete mask keeps the partial value visible and names the missing group or character count.
• The canonical value sent to the backend is derived deterministically and can be validated server-side.
• The mask does not remove browser, keyboard, or assistive technology access to label, hint, and error text.

Implementation Checklist

• Define the canonical value, formatted display value, accepted character classes, group lengths, literals, optional groups, and storage behavior before building the UI.
• Choose native input attributes such as inputmode, autocomplete, autocapitalize, maxlength, spellcheck, and aria-describedby to match the data type.
• Normalize paste from formatted and unformatted sources and test paste with spaces, dashes, parentheses, lowercase letters, and clipboard content longer than the mask.
• Preserve user control over deletion, selection, overwrite, cursor movement, undo, redo, and browser autofill.
• Validate the canonical value on client and server and show incomplete or invalid-group errors next to the field.
• Provide visible helper text for the expected format and do not make placeholder mask characters the only instruction.
• Test localization, right-to-left layouts, screen readers, mobile keyboards, zoom, saved drafts, browser Back, copy behavior, and exception values.

Common Generated-UI Mistakes

• Using a mask because a format exists even though many valid values do not fit it.
• Rejecting pasted values that include spaces, dashes, parentheses, or lowercase characters.
• Letting separators appear in the field but silently storing a different value without user or developer clarity.
• Using underscores or placeholder symbols as the only format guidance.
• Breaking deletion or middle-character correction so users must clear the entire field.
• Combining a mask with a picker or prefix/suffix that should own the format instead.
• Masking data that needs localization or exception handling without a fallback.

Critique Questions

• Is this value truly fixed-format, or are there legitimate exceptions?
• Can users paste the value from the source document and get the same result as typing?
• Can users correct one middle character without retyping the field?
• Are separators stored, displayed only, copied, or stripped before submit?
• Does the hint remain visible after the placeholder disappears?
• Would text input plus inline validation, autocomplete, prefix/suffix, or a picker be less fragile?