UX Patterns Guide
UI + UX Input And Data Entry established

Input mask

Use a mask only for stable formats, show persistent format guidance, normalize typed and pasted input into readable groups, preserve correction behavior, validate the canonical value, and provide an escape path when real values do not fit the mask.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • The value has a stable character pattern and users benefit from live grouping.
  • Formatting mirrors a source users copy from, such as a card, container, serial label, or activation key.
  • The product can handle pasted values, partial values, exceptions, and canonical storage deliberately.
  • A mask reduces transcription errors without blocking valid data.

Avoid when

  • Valid values have many lengths, regions, scripts, or exception formats.
  • Users need to enter data in a different format than the mask supports.
  • The field is better handled by a picker, autocomplete, prefix/suffix, or ordinary text input.
  • The implementation cannot preserve paste, deletion, undo, selection, and assistive technology behavior.
  • The mask hides what will be submitted or stores separators inconsistently.

Problem it prevents

Users make avoidable format errors when long codes, numbers, or identifiers require grouping, but rigid masks can also reject valid values, break paste and editing, or obscure what will actually be stored.

Pattern anatomy

What a strong implementation has to make clear

User need

The field value has known character positions, group lengths, literal separators, or check digits.

Pattern promise

Use a mask only for stable formats, show persistent format guidance, normalize typed and pasted input into readable groups, preserve correction behavior, validate the canonical value, and provide an escape path when real values do not fit the mask.

Required state

Empty untouched state with label and visible format example.

Recovery path

The mask rejects real values with different lengths, regions, scripts, or exception formats.

Access contract

Keep a real visible label and do not use the mask pattern or placeholder as a substitute for the field name.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A container number field shows the example ABCD 123456 7, groups pasted characters into that shape, and displays the raw value ABCD1234567 before submit.
  • A card-number field groups digits as users type and keeps helper text visible so the expected length does not disappear with the placeholder.
  • A user pastes abcd1234567, sees ABCD 123456 7, reviews the canonical value, and fixes one middle digit without retyping the whole code.
  • A user submits ABCD 123 and receives a precise error that the six-digit serial group and check digit are incomplete.
Weak implementation

Vague, hidden, hard to recover from

  • A phone field hard-codes a domestic mask and rejects valid international numbers.
  • The field shows underscores and separators as the only instruction, then jumps the cursor unpredictably when users paste or delete.
  • A user pastes a valid value with spaces and the mask discards characters because it only supports one-character-at-a-time typing.
  • A user enters an exception value required by a real document, but the mask blocks it with no alternative recovery path.
UI guidance
  • Show a persistent label, visible example or hint, fixed grouping, literal separators, and field-adjacent error text so users understand which characters are typed and which are supplied by the mask.
  • Keep the entered value reviewable as both a formatted display value and, when relevant, a canonical stored value so users can see what will be submitted.
UX guidance
  • Use an input mask to help users enter data that has a stable character structure, especially when grouping matches the physical document, card, container code, or serial key users are copying from.
  • Preserve normal editing behavior: users must be able to paste, delete, select, correct the middle of the value, use undo, and submit without learning the mask implementation.
Implementation contract

What the implementation must handle

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.

Interaction

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

Accessibility

  • Keep a real visible label and do not use the mask pattern or placeholder as a substitute for the field name.
  • Connect hint, format example, canonical-value note, and error text to the input with descriptive relationships where supported.
  • Do not announce every inserted separator as a disruptive status update; reserve live regions for meaningful validation or paste-normalization changes.
  • Ensure screen reader users can understand which characters they typed and which separators are supplied by the mask.

Review

  • 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?
Interactive lab

Inspect the states before you copy the pattern

Format a fixed-pattern value

Type or paste a container reference, inspect grouped formatting and raw canonical value, trigger incomplete-value validation, then compare a rigid broken mask.

Input mask
Interactive demo is ready

Launch the live UI/UX lab when you want to inspect states, keyboard behavior, and common failure modes.

State To Inspect

Empty untouched state with label and visible format example.

Keyboard / Access

Tab moves to the field in normal order and does not focus literal separators separately.

Avoid Generating

Using a mask because a format exists even though many valid values do not fit it.
Evidence trail

Source-backed claims behind this guidance

Maersk Design System: Input masks

Maersk Design System - checked

Maersk supports using masks for stable expected formats while preserving copy/paste and correction, and distinguishes masks from prefix/suffix or ordinary inputs.

SAP Fiori: Mask input

SAP - checked

SAP Fiori supports mandatory labels, mask patterns, immutable characters, aria-described guidance, paste behavior, deletion behavior, and mask avoidance when valid data would be blocked.

Material Design: Text fields

Google Material Design - checked

Material Design supports grouped formatted input, helper text, error text, and prefix/suffix alternatives for text fields.

Full agent/debug reference

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?
Accessibility
  • Keep a real visible label and do not use the mask pattern or placeholder as a substitute for the field name.
  • Connect hint, format example, canonical-value note, and error text to the input with descriptive relationships where supported.
  • Do not announce every inserted separator as a disruptive status update; reserve live regions for meaningful validation or paste-normalization changes.
  • Ensure screen reader users can understand which characters they typed and which separators are supplied by the mask.
  • Avoid placeholder symbols that create noisy or misleading announcements.
  • Maintain visible focus, text selection, high-contrast affordances, and zoom-friendly grouping.
Keyboard Behavior
  • Tab moves to the field in normal order and does not focus literal separators separately.
  • Typing fills the next editable slot while separators are inserted or skipped predictably.
  • Backspace and Delete remove editable characters without trapping focus or corrupting remaining groups.
  • Arrow keys, Home, End, selection shortcuts, paste, undo, and redo behave as close to native text editing as possible.
  • Submit with an incomplete mask moves focus to the error summary or masked field without clearing the partial value.
  • Mobile keyboards expose the needed letters, numbers, and symbols for the mask.
Variants
  • Grouped card number mask
  • Container number mask
  • Serial key mask
  • Postal code mask
  • Phone mask with fallback
  • Date mask fallback
  • Mask with literal separators
  • Mask with optional groups
  • Mask with canonical value preview
  • Paste-normalizing mask

Verification

Last verified: