blazor-devexpress-dot-blazor-dot-dxmaskedinput-1.md
A text editor supports text, numeric, date-time, and regular expression masks.
Namespace : DevExpress.Blazor
Assembly : DevExpress.Blazor.v25.2.dll
NuGet Package : DevExpress.Blazor
public class DxMaskedInput<T> :
DxMaskedInputBase<T>,
IFocusableEditor
| Name | Description |
|---|---|
| T |
The value type.
|
The DevExpress Masked Input for Blazor (<DxMaskedInput>) is a text editor that supports masks.
Most data editors work only with specific data types (DateTime, numeric objects, and so on). Date Time, Spin Edit, and Time Edit do not work when the data source stores dates or numbers as strings. Masked Input supports string values. The component converts strings from the data source to the corresponding type (DateTime, int, and so on) and then treats the value as a date or number. This allows you to use the full feature set of the selected mask type (Date-Time or Numeric) with string values.
Follow the steps below to add the Masked Input component to an application:
<DxMaskedInput>…</DxMaskedInput> markup to a .razor file.Refer to the following list for the component API reference: DxMaskedInput Members.
Blazor Masked Input does not support static render mode. Enable interactivity to use the component in your application. Refer to the following topic for more details: Enable Interactive Render Mode.
The Masked Input component supports the following mask types.
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.
Follow the steps below to apply a date-time mask:
DateTime.The following code snippet applies a date-time mask:
<DxMaskedInput @bind-Value="@Value"
Mask="@DateTimeMask.ShortDate">
<DxDateTimeMaskProperties CaretMode="@MaskCaretMode.Advancing" />
</DxMaskedInput>
@code {
DateTime Value = DateTime.Now;
}
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:
DateTimeOffset.The following code snippet applies a date-time offset mask:
<DxMaskedInput @bind-Value="@Value"
Mask="@DateTimeMask.ShortDate">
<DxDateTimeOffsetMaskProperties CaretMode="@MaskCaretMode.Advancing" />
</DxMaskedInput>
@code {
DateTimeOffset Value = DateTimeOffset.Now;
}
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.
Follow the steps below to apply a time span mask:
TimeSpan.The following code snippet applies 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 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.
Follow the steps below to apply a numeric mask:
Numeric.The following code snippet applies 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 masks allow users to enter only strings of limited length, such as phone numbers, zip codes, and social security numbers.
Follow the steps below to apply a text mask:
Text.The following code snippet applies a text mask:
<DxMaskedInput @bind-Value="Value"
Mask="(000) 000-0000" >
<DxTextMaskProperties Placeholder="Placeholder" />
</DxMaskedInput>
@code{
String Value;
char Placeholder = '#';
}
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:
RegEx.The following code snippet applies a regular expression mask:
<DxMaskedInput @bind-Value="Value"
Mask="\d{3,10}"
MaskMode="@MaskMode.RegEx">
<DxRegExMaskProperties Placeholder="Placeholder" />
</DxMaskedInput>
@code {
String Value;
char Placeholder = '#';
}
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.
If you do not use two-way data binding, handle the ValueChanged event to respond to changes made in the editor. The following code snippet 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;
}
}
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;
}
Use the SizeMode property to specify a Masked Input size. The following code snippet applies different size modes to Masked Input components.
<DxMaskedInput SizeMode="SizeMode.Small" @bind-Value="@Value" Mask="(000) 000-0000" />
<DxMaskedInput SizeMode="SizeMode.Medium" @bind-Text="@Value" Mask="(000) 000-0000" />
<DxMaskedInput SizeMode="SizeMode.Large" @bind-Text="@Value" Mask="(000) 000-0000" />
@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:
<DxMaskedInput @bind-Value="@Value"
InputCssClass="my-style"
Mask="(999) 000-00-00">
</DxMaskedInput>
@code {
string Value { get; set; }
}
.my-style {
font-family: Georgia, 'Times New Roman', Times, serif;
}
For additional information, refer to the following help topics:
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="(000) 000-00-00">
</DxMaskedInput>
@code {
string Value { get; set; }
}
Run Demo: Masked Input - Clear Button and Placeholder
You can add command buttons to the Masked Input. Refer to Command Buttons for additional information.
The following code snippet 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; } = "[email protected]";
string EmailMask { get; set; } = @"(\w|[.-])+@(\w|-)+\.(\w|-){2,4}";
string EmailLink { get; set; } = "mailto:[email protected]";
void OnEmailChanged(string email) {
Email = email;
EmailLink = $"mailto:{email}";
}
}
.dx-demo-editor-width {
max-width: 320px;
width: 100%;
}
Run Demo: Editors - Command Buttons
Refer to the following topics for base information about input validation:
You can add a standalone Masked Input or the Form Layout component to the Blazor standard EditForm. This form validates user input based on data annotation attributes defined in a model and indicates errors.
<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();
}
using System.ComponentModel.DataAnnotations;
public class Starship
{
[Required]
[StringLength(16,
ErrorMessage = "The Identifier exceeds 16 characters.")]
public string Identifier { get; set; }
// ...
}
Note that if the Mask property contains strongly required values, the input value is validated even if the corresponding model field does not have the Required data validation attribute. The following code specifies a mask for the EmployeePhone string field:
<EditForm Model="@Model" Context="EditFormContext">
<DxFormLayout>
<DxFormLayoutItem Caption="Employee Phone:" ColSpanMd="6">
<Template>
<DxMaskedInput @bind-Value="@EmployeePhone"
Mask="(999) 000-0000" />
</Template>
</DxFormLayoutItem>
@*...*@
</DxFormLayout>
</EditForm>
@code {
public string EmployeePhone { get; set; }
}
To disable input validation, set the MaskMode to RegEx and set the Mask property to a regular expression that accepts an empty string.
<EditForm Model="@Model" Context="EditFormContext">
<DxFormLayout>
<DxFormLayoutItem Caption="Employee Phone:" ColSpanMd="6">
<Template>
<DxMaskedInput @bind-Value="@EmployeePhone"
Mask="@(@"(\(\d{0,3}\)\d{3}\-\d{4})?")"
MaskMode="@MaskMode.RegEx" />
</Template>
</DxFormLayoutItem>
@*...*@
</DxFormLayout>
</EditForm>
@code {
public string EmployeePhone { get; set; }
}
An alternative solution is to use the optional digit metacharacter for all digits: Mask="(999) 999-9999".
You can use HTML attributes and events to configure the Masked Input.
<DxMaskedInput @bind-Value="@Value"
Mask="(000) 000-0000"
@onfocusout="MyFunction" />
@AlertText
@code {
string Value { get; set; }
void MyFunction()
{
AlertText = $"The Masked Input is out of focus!";
}
}
If a Blazor application throws unexpected exceptions, refer to the following help topic: Troubleshooting.
The Masked Input mask does not support full-width numerals produced by Input Method Editors (IMEs). The editor accepts only standard ASCII digits.
As a workaround, you can implement a JavaScript function that handles the component input element’s beforeinput and pasteevents to convert input data to a standard string.
Object ComponentBase DxComponentBase DxDataEditor<T> DxInputDataEditorBase<T> DxMaskedInputBase<T> DxMaskedInput<T>
See Also