Intro

The mask input control (sap.m.MaskInput) governs what a user is permitted to enter in an input field. It allows users to easily enter data in a certain format and in a fixed-width input (such as a date, time, phone number, credit card number, currency, and IP address).

Mask input example

When to Use

Use mask input if:

You have to govern what a user is allowed to enter in an input field.
You have to enter data easily in a certain format and in a fixed-width input.
You have to enter input such as a date, time, phone number, serial number, ISBN, or product activation key.
You want to group multiple suboptions under a parent option, and require an intermediate selection state (tri-state). The tri-state indicates that some (but not all) suboptions are selected.

Don't

Don’t use mask input if:

The mask prevents users from entering essential data.
The users need to enter data in a format other than the one used by the mask (for example, if users have to enter a phone number with a format for a different region).

Use when the input needs to follow a specific format, such as a phone number.

Avoid using a mask if it limits user entry – for example, when fixed-length placeholder format prevents users from entering longer values, such as email addresses.

Anatomy

The mask input has three parts:

Label: Describes the purpose of the input field.
Input Field: Editable area where users can type.
Mask Pattern: Defines the expected format and structure of the input.

Mask input anatomy

Components

The mask input control has a fixed length format to which the user’s input must conform. This can be particularly useful when the user needs to enter text or numbers with specific formatting, such as a phone number, postal code, or credit card number.

Mask input or a placeholder text are not substitutes for the input label. Using a label is mandatory. Placeholder texts in an input field are optional. Note that if there is no placeholder text, the input field will initially look empty. The mask formatting is revealed as soon as the focus is on the field.

Mask input without placeholder text

Mask input with placeholder text

hint

Use the ariaDescribedBy association in the sap.m.InputBase control to provide additional descriptive text for screen readers. This improves accessibility by letting assistive technologies announce extra guidance (such as units of measurement or input instructions) when the user focuses on the input field.

Immutable Characters

When defining the mask format, the developer can place immutable characters, such as brackets and dashes, in specific positions. The format also specifies the range of valid characters for each separate position, thus preventing the user from entering invalid input.

For example, when the user enters a product activation key, the vendor prefix and the dashes between input groups are already present.

Product activation key example with immutable characters

Behavior and Interaction

Entering Text

The mask pattern appears in the input field when it receives focus.
The default placeholder symbol is “_” but can be customized.
"When users start typing into a mask input, each character they enter replaces the placeholder symbol (like _) in the positions defined by the mask."

Entering text into a mask input when a custom placeholder symbol is used (instead of the default underscore _) to guide user input.

Copying and Pasting

Copying to a mask input field:

Users can copy both formatted and unformatted strings into a mask input field. When the texts are pasted, they take on the format defined for the mask input field.

Example: Mask input field for a number with the format: (000) 000 000000

<div> <div>Copied source string</div> <div>Value in mask input field after pasting</div> </div> <div> <div>(555) 333 123456</div> <div>(555) 333 123456</div> </div> <div> <div>555-333-123456</div> <div>(555) 333 123456</div> </div> <div> <div>555 (333) 12 34 56</div> <div>(555) 333 123456</div> </div>

Copying from a mask input field:

If you copy a string from a mask input field and paste it elsewhere, the format of the mask input field is copied as well.

information

For information on how to manage leading and trailing white space (blanks) when copying and pasting text into input controls, please see removing leading and trailing white space.

Deleting Content

Deleting characters from a masked input field replaces each removed character with a placeholder symbol (“_”), while preserving the position of the remaining input. The mask structure stays fixed and does not shift.

Deleting individual characters in mask input

Selecting the entire string deletes all characters in the input, which are automatically replaced with placeholder symbols.

Deleting all characters in mask input

Responsiveness

Mask input extends the input control (sap.m.Input) and has all the normal properties of an input field.

Guidelines

Validation Rules

Another option is to define new validation rules, such as allowing lowercase characters from “a” to “e” only. This is particularly flexible because these rules are defined with regular expression syntax.

The mask comes with two predefined validation rules: one for all characters in the English alphabet, and one for the numbers from zero to ten.

Therefore, when the mask format is being defined, the alphabetic rule is represented by the letter “a”, and the numeric rule by the number “9”. For example, a numeric mask format with a length of five characters would be specified as “99999”, a mask that accepts only alphabetical characters would be specified as “aaaaa”, and a mixed mask could be “aaa99”. In the mixed mask example, the user would not be able to enter numeric characters anywhere other than in the last two positions.

When you create the MaskInput instance, you can specify the following settings:

Mask: The format specification, such as (123) 999-999.
PlaceholderSymbol: A single character used to represent empty positions in a mask value, such as _ _ _ _ _.
Rules: A collection of sap.m.MaskInputRule instances.

Unit of Measurement

You can use the layout options of the form to add the unit of measurement (UoM) after the mask input control. Apps can use the label-field ratio to show the UoM after the field. However, you must make sure that the UoM is properly visualized and doesn’t wrap to the next row.

hint

For accessibility purposes, you can use “ariaDescribedBy” from the input control.

Localization

The mask input supports both Left-to-right and Right-to-left modes of writing. The label sits to the left of the input field in Left-to-right languages and to the right of the input field in Right-to-left languages.