Mask and Prompt
This article explains the relationship and the configuration options that tie the Mask, the prompts and the Value of the Telerik MaskedTextbox for Blazor. The settings and behaviors described below let you customize the behavior of the component and what data you will get out of it.
This article contains the following sections:
Mask
The Mask is the main feature of the component. It defines what input is allowed from the user at what positions so they must obey those requirements. By default, the mask is constantly shown, but you can change that to also show a FloatingLabel or Placeholder.
You can use special characters called Rules in the Mask to define its behavior. The other characters that have no special meaning but are always shown and the user cannot change them are called Literal characters.
Rules
The Telerik MaskedTextbox provides a set of built-in rules that it recognizes as special characters when encountered in the Mask and they are the main feature of the component that determines how the user writes their input. The reference list below shows the rules and what they do.
List of Rules (special characters) that define a mask behavior
-
0- Digit (0-9) -
9- Digit (0-9) orspace -
#- Digit (0-9),space, plus (+) and minus (-) signs -
L- Letter (a-Z) -
?- Letter (a-Z) orspace -
A- Alphanumeric (0-9, a-Z) -
a- Alphanumeric (0-9, a-Z) orspace -
&- Character (excludingspace) -
C- Character orspace
You can find some examples of different masks in the Masks Live Demo and in the Some Sample Masks section of the documentation.
Literals
Apart from the rules, you can also use static symbols in the mask pattern that are also known as literals. In the masked value, a literal is always rendered on the same position as the position where it is defined in the mask property and the user cannot change it. You can use them to show a more user-friendly format of the message, or to predefine some of the input for your user.
In some cases, you may want to include a literal that matches a Rule, however. To do that, you need to escape the symbol with the slash (\) character. An escaped rule turns into a literal.
Literals and escaped rules as part of the mask
@* The user will see "ABC---1209" in this example and only the part "12" is editable. The other symbols are escaped rules - "A", "C", "0" and "9" or literals - the "B" and the three dashes "-" *@
@invoiceNumber
<TelerikMaskedTextBox Mask="\AB\C---00\0\9" @bind-Value="@invoiceNumber"></TelerikMaskedTextBox>
@code{
string invoiceNumber { get; set; } = "12";
}
Include Literals in the Value
By default, the Value of the component only includes the rules from the mask. You can, however, also include the literal characters by setting the IncludeLiterals parameter to true.
Adding the literals to the value
@* Toggle the checkbox to see the behavior *@
<TelerikMaskedTextBox Mask="(+999) 000-0000"
@bind-Value="@TheValue"
IncludeLiterals="@ShouldAddLiterals">
</TelerikMaskedTextBox>
<span style="white-space: pre;">
@TheValue
</span>
<label><input type="checkbox" @bind="@ShouldAddLiterals" /> Include literals</label>
@code{
string TheValue { get; set; } = "44 5556666"; // the space accounts for three-digit codes
bool ShouldAddLiterals { get; set; }
}
Mask on Focus, FloatingLabel and Placeholder
The MaskOnFocus parameter lets you instruct the component to show the mask only when the user is about to type in the input - when it is focused. This lets you show the FloatingLabel or Placeholder that you can set so you can provide an easier to read prompt first, before you show the actual format to your users.
The FloatingLabel will take precedence over the Placeholder if the MaskedTextBox is not focused. Neither will be shown if there is a Value already. You should use the Placeholder instead of a FloatingLabel if you do not want the animated effect or the increased height it causes.
Showing the mask on focus only
@* This is the non-default behavior where the user first sees the FloatingLabel or Placeholder if there is no value *@
@TheValue
<br />
<TelerikFloatingLabel Text="Credit Card Number:">
<TelerikMaskedTextBox MaskOnFocus="true"
Mask="0000-0000-0000-0000"
@bind-Value="@TheValue">
</TelerikMaskedTextBox>
</TelerikFloatingLabel>
@code {
string TheValue { get; set; }
}
Prompt
The prompt characters are the hints that the user sees in the mask where they have not written values yet. By default, they are underscores _. You can change it by setting the Prompt parameter to the desired char.
To make the Prompt character invisible, set it to a space like this:
<TelerikMaskedTextBox Prompt="' '" />
When the user has not filled in all the blank spaces in the mask, the Telerik Masked Textbox will replace them with the PromptPlaceholder in the Value that it will set in the view-model. By default, the char that is used is a simple space (). If you don't want such characters in the Value, set PromptPlaceholder="null". Note that HTML rendering combines spaces into one by default.
The PromptPlaceholder is useful when you need to process the user input at a later stage. For example, when you can have input that can vary in length like a phone country code (that can be one to three digits and the rest can be empty or spaces). For such cases, the masked textbox provides you with the value where places where the user did not input anything are replaced with the PromptPlaceholder to facilitate post-processing and parsing. For example, with the default space for a placeholder, you could remove all spaces from the input to get only the meaningful digits of the phone number.
Prompt and PromptPlacehlolder behavior
@* Toggle the checkboxex and write a part of the card number to see the difference in the Value and input appearance *@
<div style="white-space: pre; text-decoration: underline;font-family: 'Courier New';">@TheValue</div>
<div>
<label><input type="checkbox" @bind="@CustomPrompt" />Use custom Prompt</label>
<br />
<label><input type="checkbox" @bind="@CustomPromptPlaceholder" />Use custom PromptPlaceholder</label>
</div>
<TelerikMaskedTextBox PromptPlaceholder="@( CustomPromptPlaceholder ? "a"[0] : ' ' )"
Prompt="@( CustomPrompt ? "*"[0] : '_' )"
Mask="0000-0000-0000-0000" @bind-Value="@TheValue">
</TelerikMaskedTextBox>
@code{
string TheValue { get; set; }
bool CustomPrompt { get; set; }
bool CustomPromptPlaceholder { get; set; }
}
You can see the behavior of the prompt features in the Customization Live Demo.
You should not set the
PromptPlaceholderto a character that can be valid for the user input in the current mask. Doing so can result in those characters showing up in the user input without the user writing them.For example, if you have a mask
00-00andPromptPlaceholderis4, when the user writes1in the input, the actualValuewill become14-44even though the user sees1_-__, and when the component re-renders (for example, because anEventCallbackfired), the user will see14-44which is not what they entered or expected.