DxMaskedInput<T> Class

A text editor supports text, numeric, date-time, and regular expression masks.

Namespace: DevExpress.Blazor

Assembly: DevExpress.Blazor.v23.2.dll

NuGet Package: DevExpress.Blazor

Declaration

public class DxMaskedInput<T> :
    DxMaskedInputBase<T>,
    IFocusableEditor

Type Parameters

Name	Description
T	The value type.

Remarks

The DevExpress Masked Input for Blazor (<DxMaskedInput>) is a text editor that supports masks.

Most of our data editors can work only with certain data types (DateTime, numeric objects, and so on), but you cannot use these editors (Date Time, Spin Edit, Time Edit) if you store the data source objects (dates or numbers) as strings. The Masked Input can work with such data. The component converts strings from the data source to the corresponding data type (DateTime, int, and so forth), and then treats the resulting value as a date or number. This allows you to use all the functionality of the appropriate mask type (Date-Time, Numeric), even for string objects.

Run Demo: Masked Input

Add a Masked Input to a Project

Follow the steps below to add the Masked Input component to an application:

1. Use a DevExpress Project Template to create a new Blazor Server or Blazor WebAssembly application. If you use a Microsoft project template or already have a Blazor project, configure your project to incorporate DevExpress Blazor components.
2. Add the <DxMaskedInput>…</DxMaskedInput> markup to a .razor file.
3. Configure the component: apply a mask, specify the editor’s value, handle value changes, and so on (see the sections below).

Apply a Mask

The Masked Input component supports the following mask types.

Date-Time

Date-time masks allow users to enter only date and/or time values. Users can navigate between mask sections (such as months, days, and hours) and increase/decrease section values with the Up and Down arrow keys and mouse wheel.

Run Demo: Date-Time Mask

Follow the steps below to apply a date-time mask:

1. Make sure that the Value property is set to a DateTime object or a compatible String (for instance, “11/09/2022”). In the latter case, set the MaskMode property to DateTime.
2. Assign a predefined or custom pattern to the Mask property.
3. Optional. Add the DxDateTimeMaskProperties component to the Masked Input markup to customize mask settings.

The example below demonstrates how to apply a date-time mask:

<DxMaskedInput @bind-Value="@Value"
            Mask="@DateTimeMask.ShortDate">
    <DxDateTimeMaskProperties CaretMode="@MaskCaretMode.Advancing" />
</DxMaskedInput>

@code {
    DateTime Value = DateTime.Now;
}

Date-Time Offset

Date-time offset masks allow users to enter only date and/or time values, including the time’s offset from Coordinated Universal Time (UTC). Users can navigate between mask sections (such as months, days, and hours) and increase/decrease section values with the Up and Down arrow keys and mouse wheel.

Run Demo: Date-Time Offset Mask

Follow the steps below to apply a date-time offset mask:

1. Make sure that the Value property is set to a DateTimeOffset object or a compatible String (for instance, “11/09/2022”). In the latter case, set the MaskMode property to DateTimeOffset.
2. Assign a predefined or custom pattern to the Mask property.
3. Optional. Add the DxDateTimeOffsetMaskProperties component to the Masked Input markup to customize mask settings.

The example below demonstrates how to apply a date-time offset mask:

<DxMaskedInput @bind-Value="@Value"
            Mask="@DateTimeMask.ShortDate">
    <DxDateTimeOffsetMaskProperties CaretMode="@MaskCaretMode.Advancing" />
</DxMaskedInput>

@code {
    DateTimeOffset Value = DateTimeOffset.Now;
}

Time Span

Time span masks allow users to enter only time intervals. Users can navigate between mask sections (such as days, hours, and minutes) and increase/decrease section values with the Up and Down arrow keys and mouse wheel.

Run Demo: Time Span Masks

Follow the steps below to apply a time span mask:

1. Make sure that the Value property is set to a TimeSpan object or a compatible String (for instance, “5:16:30:15”). In the latter case, set the MaskMode property to TimeSpan.
2. Assign a predefined or custom pattern to the Mask property.
3. Optional. Add the DxTimeSpanMaskProperties component to the Masked Input markup to customize mask settings.

The example below demonstrates how to apply a time span mask:

<DxMaskedInput @bind-Value="@Value"
            Mask="@TimeSpanMask.GeneralShortFormat">
    <DxTimeSpanMaskProperties CaretMode="@MaskCaretMode.Advancing" />
</DxMaskedInput>

@code {
    TimeSpan Value = new TimeSpan(6, 25, 30);
}

Numeric

Numeric masks allow users to enter only numeric values. Users can navigate between digits and increase/decrease digit values with the Up and Down arrow keys and mouse wheel.

Run Demo: Numeric Mask

Follow the steps below to apply a numeric mask:

1. Make sure that the Value property is set to a numeric object or a compatible String (for instance, “1234567”). In the latter case, set the MaskMode property to Numeric.
2. Assign a predefined or custom pattern to the Mask property.
3. Optional. Add the DxNumericMaskProperties component to the Masked Input markup to customize mask settings.

The example below demonstrates how to apply a numeric mask:

<DxMaskedInput @bind-Value="@Value"
            Mask="@NumericMask.RealNumber">
    <DxNumericMaskProperties Culture="Culture" />
</DxMaskedInput>

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

Text

Text masks allow users to enter only strings of limited length, such as phone numbers, zip codes, and social security numbers.

Run Demo: Text Mask

Follow the steps below to apply a text mask:

1. Make sure that the Value property is set to a String object or the MaskMode property is set to Text.
2. Combine metacharacters, special characters, and literal characters to create a mask pattern and assign it to the Mask property.
3. Optional. Add the DxTextMaskProperties component to the Masked Input markup to customize mask settings.

The example below demonstrates how to apply a text mask:

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

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

Regular Expression

If the mask types listed above do not meet your requirements, you can use regular expression masks. This mask type allows you to create advanced masks of variable lengths with multiple acceptable patterns and a limited range of character input.

Run Demo: Regular Expression Mask

Follow the steps below to apply a regular expression mask:

1. Set the MaskMode property to RegEx.
2. Combine metacharacters, quantifiers, and literal characters to create a mask pattern and assign it to the Mask property.
3. Optional. Add the DxRegExMaskProperties component to the Masked Input markup to customize mask settings.

The example below demonstrates how to apply a regular expression mask:

<DxMaskedInput @bind-Value="Value"
               Mask="\d{3,10}" 
               MaskMode="@MaskMode.RegEx">
    <DxRegExMaskProperties Placeholder="Placeholder" />
</DxMaskedInput>

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

Edit Value

Use the Value property to specify an editor value or to bind the displayed text to a data source object. You can use the @bind attribute to bind the Value property to a data field. Refer to the following topic for details: Two-Way Data Binding.

Also, the specified value should fit the Mask pattern. Otherwise, the value cannot be displayed.

<DxMaskedInput @bind-Value="Value" Mask="[A-Z]*" MaskMode="MaskMode.RegEx"/>

@code {
    string Value { get; set; } = "TEXT";
}

The Value property updates its value when the editor loses focus (OnLostFocus mode). You can set the BindValueMode property to OnInput or OnDelayedInput to update the Value property when a user changes the input value.

Handle a Value Change

If you do not use two-way data binding, handle the ValueChanged event to respond to changes made in the editor. The code below enables the Update Text button once a user types in the Masked Input editor.

<DxMaskedInput Value="Value"
               ValueChanged="@((int newValue) => OnValueChanged(newValue))"
               Mask="@NumericMask.Currency">
</DxMaskedInput>
<DxButton Enabled="@IsEnabled">Update Value</DxButton>

@code {
    int Value = 0;
    bool IsEnabled = false;

    void OnValueChanged(int newValue)
    {
        Value = newValue;
        if (newValue != 0)
            IsEnabled = true;
        else IsEnabled = false;
    }
}

Disabled and ReadOnly Modes

Use the Enabled and ReadOnly properties to disable and mark the Masked Input component as read-only.

<DxMaskedInput @bind-Value="@Value"
               Mask="@NumericMask.Currency"
               ReadOnly="true">
</DxMaskedInput>

<DxMaskedInput @bind-Value="@Value"
               Mask="@NumericMask.Currency"
               Enabled="false">
</DxMaskedInput>

@code {
    double Value { get; set; } = 123.45;
}

Appearance Customization

Use the SizeMode property to specify a Masked Input size. The code below applies different size modes to Masked Input components.

<DxMaskedInput SizeMode="SizeMode.Small" @bind-Value="@Value" Mask="[phone]" />

<DxMaskedInput SizeMode="SizeMode.Medium" @bind-Text="@Value" Mask="[phone]" />

<DxMaskedInput SizeMode="SizeMode.Large" @bind-Text="@Value" Mask="[phone]" />

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

To apply custom CSS rules to Masked Input, use the InputCssClass property. The following code snippet changes the component font:

<style>
    .my-style {
        font-family: Georgia, 'Times New Roman', Times, serif;
    }
</style>

<DxMaskedInput @bind-Value="@Value" 
                InputCssClass="my-style"
                Mask="[phone]">
</DxMaskedInput>

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

For more information, refer to the following help topics:

• Size Modes
• CSS Classes

Clear Button and Placeholder

Set the ClearButtonDisplayMode property to Auto to display the Clear button in the Masked Input editor when it is not empty. Use the NullText property to display the prompt text (placeholder) in the editor when its value is null.

<DxMaskedInput @bind-Value="@Value"
               ClearButtonDisplayMode="DataEditorClearButtonDisplayMode.Auto"
               NullText="Specify a phone..."
               Mask="[phone]">
</DxMaskedInput>

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

Run Demo: Masked Input - Clear Button and Placeholder

Add Command Buttons

You can add command buttons to the Masked Input. Refer to Command Buttons for more information.

The code below adds the Send E-mail button to the Masked Input component.

<DxMaskedInput Value="@Email"
               ValueChanged="@((string value) => OnEmailChanged(value))"
               Mask="@EmailMask"
               MaskMode="MaskMode.RegEx">
    <Buttons>
        <DxEditorButton IconCssClass="editor-icon editor-icon-mail"
                        Tooltip="Send Email"
                        NavigateUrl="@EmailLink"
                        CssClass="dx-demo-editor-width" />
    </Buttons>
</DxMaskedInput>


@code{
    string Email { get; set; } = "[e-mail]";
    string EmailMask { get; set; } = @"(\w|[.-])+@(\w|-)+\.(\w|-){2,4}";
    string EmailLink { get; set; } = "mailto:[e-mail]";
    void OnEmailChanged(string email) {
        Email = email;
        EmailLink = $"mailto:{email}";
    }
}

<style>
    .dx-demo-editor-width {
        max-width: 320px;
        width: 100%;
    }
</style>

Run Demo: Editors - Command Buttons

Input Validation

You can add a standalone Masked Input or the Form Layout component to the Blazor’s standard EditForm. This form validates user input based on data annotation attributes defined in a model and indicates errors.

Razor

<EditForm Model="@starship" Context="EditFormContext">
    <DataAnnotationsValidator />
    <DxFormLayout >
        <DxFormLayoutItem Caption="Identifier:" ColSpanMd="6" >
            <Template >
                <DxMaskedInput @bind-Value="@starship.Identifier" Mask=".{,16}" MaskMode="@MaskMode.RegEx" />
            </Template >
        </DxFormLayoutItem >
        @*...*@
    </DxFormLayout>
</EditForm>

@code {
    private Starship starship=new Starship();
}

Starship

using System.ComponentModel.DataAnnotations;

public class Starship
{
    [Required]
    [StringLength(16,
    ErrorMessage = "The Identifier exceeds 16 characters.")]
    public string Identifier { get; set; }
    // ...
}

For more information, refer to the following help topic: Validate Input.

Run Demo: Form Validation

HTML Attributes and Events

You can use HTML attributes and events to configure the Masked Input.

<DxMaskedInput @bind-Value="@Value"
               Mask="[phone]"
               @onfocusout="MyFunction" />

@AlertText

@code {
    string Value { get; set; }

    void MyFunction()
    {
        AlertText = $"The Masked Input is out of focus!";
    }
}

Troubleshooting

If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.

Implements

IHandleEvent

IHandleAfterRender

IAsyncDisposable

IComponent

Inheritance

Object

ComponentBase

DevExpress.Blazor.Base.DxAsyncDisposableComponent

DevExpress.Blazor.Base.DxDecoratedComponent

DxComponentBase

DxDataEditor<T>

DxInputDataEditorBase<T>

DxMaskedInputBase<T>

DxMaskedInput<T>