Skip to main content

Masks

  • 6 minutes to read

Most DevExpress Blazor text editors support masked input.

Data Editors - Masks

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.

    Date-Time Masks

  • 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.

    Numeric Masks

  • 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.

    Text Masks

  • 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.

    Regular Expression Masks

Data Editors that Support Masks

Editor

Supported mask types(s)

Related API

Samples

Date Edit

Date-time

Mask

DxDateTimeMaskProperties

CaretMode

Custom Date-Time Masks

Date-Time Masks - Abbreviated Month Name

Masked Input

(text editor)

Date-time

Numeric

Text

Regular Expression

Mask

MaskMode

DxTextMaskProperties

DxRegExMaskProperties

Date-Time Masks - Masked Input

Text Masks - Phone Number

Regular Expression Masks - E-Mail Address

Regular Expression Masks - IP Address

Spin Edit

Numeric

Mask

DxNumericMaskProperties

Numeric Masks - Integer Numbers

Numeric Masks - X Decimal Places

Time Edit

Date-Time

Mask

DxDateTimeMaskProperties

CaretMode

Date-Time Masks - Long Time

Date-Time Masks - Short Time

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:

  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();
    

The described mode is activated in our Blazor Server demos for the Masked Input component. Click the button below to see how this approach works online.

Run Demo: Masked Input

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="(000) 000-0000" >
    <DxTextMaskProperties Placeholder="Placeholder" />
</DxMaskedInput>

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

Text Masks - Custom 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; }
}

Text Masks - Empty Alpha-Numeric Sequence

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.

Regular Expression Masks - Strong Autocompletion Mode

If a user adds r to the editor’s value, the component completes the input and displays March:

Regular Expression Masks - Strong Autocompletion Mode

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:

Regular Expression Masks - Optimistic Autocompletion Mode

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:

Regular Expression Masks - Optimistic Autocompletion Mode

None

The autocomplete feature is disabled. A user must type each character into the edit box.