Text Masks

Apr 18, 2023
4 minutes to read

The Text mask type allows users to enter alphabetic, numeric or alphanumeric characters at specific positions in the Masked Input text editor. Use this mask type for editors that should accept phone numbers, zip codes, social security numbers, and so on.

Run Demo: Masked Input — Text Mask

Text masks impose the following requirements on editor value type:

Set the Value property to the String object.
If you bind the component’s edit value to an object other than String, set MaskMode to MaskMode.Text.

For information on other mask types, refer to the following topic: Masks.

Apply a Mask

A Text mask defines a string that can consist of metacharacters, and special and literal characters. To apply a mask to the Masked Input, assign the required pattern (see the sections below) to the DxMaskedInput.Mask property.

The DxTextMaskProperties component specifies additional mask-related settings (for example, a placeholder, caret mode, or current culture).

razor

<DxMaskedInput @bind-Value="Value"
               Mask="(000) 000-0000" >
    <DxTextMaskProperties Placeholder="Placeholder" />
</DxMaskedInput>

@code{
    String Value { get; set; }
    char Placeholder = '#';
}

Metacharacters

A metacharacter specifies a range of characters that users can enter. The following table lists the available metacharacters.

Character	Description
`L`	A mandatory alphabetic character. For example, A-Z, a-z for the U.S.
`l`	An optional alphabetic character.
`A`	A mandatory alphanumeric character. For example, A-Z, a-z, 0-9 for the U.S.
`a`	An optional alphanumeric character.
`C`	A mandatory arbitrary character.
`c`	An optional arbitrary character.
`0`	A mandatory numeric character.
`9`	An optional numeric character.
`#`	An optional numeric character or a plus or minus sign.

Special Characters

Special characters convert to uppercase/lowercase, add date/time separators, and so forth. The following table lists the available special characters.

Character	Description
`>`	Converts subsequent characters to uppercase.
`<`	Converts subsequent characters to lowercase.
`<>`	Discards case conversion for subsequent characters.
`/`	Separates months, days, and years. The culture’s DateSeparator property specifies the actual character.
`:`	Separates hours, minutes, and seconds. The culture’s TimeSeparator property specifies the actual character.
`$`	Inserts the currency symbol. The culture’s CurrencySymbol property specifies the actual character.

Placeholders

Use the Placeholder property to specify an input prompt character. The default value is an underscore (_).

razor

<DxMaskedInput @bind-Value="Value"
               Mask="(000) 000-0000" >
    <DxTextMaskProperties Placeholder="Placeholder" />
</DxMaskedInput>

@code{
    String Value { get; set; }
    char Placeholder = '#';
}

Literal Characters

Literal characters are arbitrary read-only characters in the edit box. If you add a character that is not a meta or special character to a mask expression, the character is displayed in the edit box as is. To display a meta or special character as a literal, precede it with a backslash.

A user has no need to enter literal characters (the cursor skips over them).

razor

<DxMaskedInput @bind-Value="Value" 
               Mask="@(@"\A>LL-00")" >
</DxMaskedInput>

@code{
    String Value { get; set; }
}

Literal characters are saved to the Masked Input’s Value. To change this behavior and do not save literals to the editor’s value, set the SaveLiteral property to false.

razor

<DxMaskedInput @bind-Value="Value"
               Mask="(000) 000-0000">
    <DxTextMaskProperties SaveLiteral="false" />
</DxMaskedInput>

@code{
    String Value { get; set; }
}

User Scenarios

Phone Number

razor

<DxMaskedInput @bind-Value="Value"
               Mask="(000) 000-0000">
</DxMaskedInput>

@code{
    String Value { get; set; }
}

The (000) 000-0000 mask allows users to enter a phone number. Each ‘0’ metacharacter requires a user to enter a digit. Dashes and parentheses are literals.

Value is not entered:
Value is entered:

Phone Number with an Optional Area Code

razor

<DxMaskedInput @bind-Value="Value"
               Mask="(999) 000-0000">
</DxMaskedInput>

@code{
    String Value { get; set; }
}

The (999) 000-0000 mask allows users to enter a phone number with an optional area code. Each ‘ 9 ‘ metacharacter allows users to omit a digit.

Alpha-Numeric Sequence

razor

<DxMaskedInput @bind-Value="Value" 
               Mask="\A>LL-00">
</DxMaskedInput>

@code{
    String Value { get; set; }
}

The \A>LL-00 mask allows users to enter two upper-case letters and two numbers separated by a dash and preceded with the ‘ A ‘ literal. A backslash precedes the literal to distinguish it from a metacharacter.

Value is not entered:
Value is entered:

CPF Number

razor

<DxMaskedInput @bind-Value="Value"
               Mask="000.000.000-00">
</DxMaskedInput>

@code{
    String Value { get; set; }
}

The 000.000.000-00 mask allows users to enter a CPF number. Each ‘0’ metacharacter requires a user to enter a digit. Dashes and dots are literals.