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).
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.
Do not 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).
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.
It is possible to add additional descriptive texts to the input field (a unit of measurement, for example) by using a new association in the
sap.m.InputBase control called
ariaDescribedBy. The association is responsible for referencing the elements that describe the control.
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 phone number, the area code in brackets and the space between the numbers are already present.
Note that the sap.m.MaskInput control extends sap.m.Input and has all the normal properties of an input field.
When creating a new mask, the developer can change the configuration of some default properties. For example, the default placeholder symbol “_” can be changed to something else.
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
|Copied source string||Value in mask input field after pasting|
|(555) 333 123456||(555) 333 123456|
|555-333-123456||(555) 333 123456|
|555 (333) 12 34 56||(555) 333 123456|
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.
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
The mask is defined by its character type (or by its length, as applicable). You should consider the following important facts:
- The mask characters normally correspond to an existing rule (one rule per unique character). Characters that do not are considered immutable characters. For example, the mask ‘2099’, where ‘9’ corresponds to a rule for digits, has ‘2’ and ‘0’ as immutable characters.
- Adding a rule that corresponds to the symbol placeholder is not recommended and would lead to unpredictable behavior.
Placeholder symbol string “_”
This defines a placeholder symbol. It is shown in a position where there has not yet been any user input.
Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.