Masks

• Nov 24, 2022
• 6 minutes to read

Most DevExpress Blazor text editors support masked input.

Run Demo

Mask Types

Blazor text editors support the following mask types:

• Date-time

  This mask type allows users to enter only date and/or time values. To specify the mask, choose from a number of predefined patterns or use standard .NET Framework format strings. Users can navigate between value sections (days, months, years, hours, and so forth) and increment/decrement values with the keyboard and mouse wheel.

  

• Numeric

  Use this mask type when you want to restrict input to numeric values. You can use predefined mask patterns or standard numeric .NET format strings to specify the mask. For example, to restrict input to currency values, specify the Currency numeric mask. Literal characters, such as currency symbols, are displayed but not saved as part of the editor value. The mask also does not allow more than two digits after the decimal point. Users can navigate between digits and increase or decrease their values using the Up and Down arrows or mouse wheel.

  

• Text

  Apply this mask type when users must enter strings of limited length, such as phone numbers, zip codes, social security numbers, and so on. Some characters in the mask string serve as placeholders for digits or letters, while others are literals used to separate value sections. An example of such literals is parentheses for the area code in a phone number.

  

• Regular Expression

  If the mask types listed above do not meet your requirements, you can use regular expressions. The syntax is similar to the POSIX ERE specification.

  

Data Editors that Support Masks

Editor	Supported mask types(s)	Related API	Samples
Date Edit	Date-time	Mask DxDateTimeMaskProperties CaretMode
Masked Input (text editor)	Date-time Numeric Text Regular Expression	Mask MaskMode DxTextMaskProperties DxRegExMaskProperties
Spin Edit	Numeric	Mask DxNumericMaskProperties
Time Edit	Date-Time	Mask DxDateTimeMaskProperties CaretMode

Apply a Mask

To set up a mask expression in code, use an editor’s Mask property (see the table above). Additionally, you can use the Dx...MaskProperties components (DxDateTimeMaskProperties and similar) to configure mask settings.

The code below enables the French culture and applies a Currency mask to the Spin Edit.

@using System.Globalization

<DxSpinEdit @bind-Value="Value"
            Mask="@NumericMask.Currency">
    <DxNumericMaskProperties Culture="Culture" />
</DxSpinEdit>

@code{
    Double Value { get; set; }
    CultureInfo Culture = CultureInfo.GetCultureInfo("fr-FR");
}

To enable a Regular Expression mask, you should also set the MaskMode property to MaskMode.RegEx.

<DxMaskedInput @bind-Value="Value"
               Mask="\d+(\R.\d{0,2})?"
               MaskMode="MaskMode.RegEx">
</DxMaskedInput>

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

Optimize Mask Performance in Blazor Server Apps

DevExpress data editors allow you to enable client-side (WebAssembly) masks in Blazor Server applications. In this mode, data editors with masks process input text on the client side to reduce input delays when you have a slow connection.

The mode’s basic principles are listed below:

• Output (masked) values of client-side and server-side mask modes are identical.
• DevExpress data editors for Blazor use mono WebAssembly Runtime to implement client-side mask logic.
• A browser downloads mask-related files if only it is necessary. For example, when a user opens a page with an editor that uses masks. If a user’s browser uses caching, the files are only downloaded once and then stored in the cache.
• When a user interacts with the editor, the component sends requests to a mono machine. The machine processes the received value and responds with the result (text, a caret position, and so on).
• The editor requests the server if only the component’s value is updated.

To activate this functionality, follow the steps below:

.NET 5.0

1. Install the DevExpress.Blazor.Server.WebAssembly NuGet Package.

2. Register the middleware. Call the UseDevExpressBlazorWasmMasksStaticFiles(IApplicationBuilder) method from the Startup.cs file’s Configure method:

   using Microsoft.AspNetCore.Builder;
   using Microsoft.Extensions.DependencyInjection;
   
   public void Configure(IApplicationBuilder app, IHostingEnvironment env) {
       // ...
       app.UseStaticFiles();
       app.UseDevExpressBlazorWasmMasksStaticFiles();
       // ...
   }
   

3. Set up mask-related options. Call the AddDevExpressBlazorWasmMasks(IServiceCollection) method from the Startup.cs file’s ConfigureServices method:

   using Microsoft.Extensions.DependencyInjection;
   
   public void ConfigureServices(IServiceCollection services) {
       // ...
       services.AddDevExpressBlazor();
       services.AddDevExpressBlazorWasmMasks();
   }
   

.NET 6.0

1. Install the DevExpress.Blazor.Server.WebAssembly NuGet Package.

2. Register the middleware. Call the UseDevExpressBlazorWasmMasksStaticFiles(IApplicationBuilder) method in the Program.cs file:

   app.UseDevExpressBlazorWasmMasksStaticFiles();
   

3. Set up mask-related options. Call the AddDevExpressBlazorWasmMasks(IServiceCollection) method in the Program.cs file:

   builder.Services.AddDevExpressBlazorWasmMasks();
   

Change Placeholder Characters

The default character placeholder is an underscore (_).

You can specify a custom placeholder for Text and Regular Expression masks. Use the DxTextMaskProperties.Placeholder and DxRegExMaskProperties.Placeholder properties, respectively.

<DxMaskedInput @bind-Value="Value"
               Mask="[phone]" >
    <DxTextMaskProperties Placeholder="Placeholder" />
</DxMaskedInput>

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

Exclude Mask Characters from an Editor’s Value

Literal characters are arbitrary read-only characters displayed in the edit box. If you add a character that is not a meta or special character into a Text mask expression, the character is displayed in the edit box as is. A user has no need to enter literal characters (the cursor skips over them).

To exclude these characters from the text returned by the editor’s Value property, set SaveLiteral to false.

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

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

Automatic Completion

Use the MaskAutoCompleteMode property to enable automatic completion in Regular Expression masks. The following auto-complete modes are supported:

Autocomplete mode	Description
Strong (default)	Each time a user types a character, the editor determines if the following placeholder can be filled. If only a specific character can be inserted in this position, the editor displays this character, and moves the caret to the right of this character. For example, if the mask is \R{MonthNames} (the editor accepts month names only) and a user types M, the second placeholder is filled with the a character, since there are two months that start with M (March and May) and both contain an a in the second position. If a user adds r to the editor’s value, the component completes the input and displays March:
Optimistic	When a user enters a character in the empty edit box for the first time, the editor fills all the following placeholders with the default values. 0 is the default character for placeholders that accept only numeric values. For placeholders that accept letters, a is the default character. For example, if the mask is set to \R{MonthNames} (the editor accepts month names only) and a user types M, the editor completes the value and sets it to May (which is the shorter of the two options - March and May). The y character becomes selected so that a user can easily change it: Another example is when the mask is set to \d{3}-\d{2}-\d{2} (a telephone number pattern) and a user enters a character (for instance, 1) in the empty edit box. The editor fills the following placeholders with the default values (the 0 characters) and selects them:
None	The autocomplete feature is disabled. A user must type each character into the edit box.