Class SfMaskedTextBox

The MaskedTextBox is an input element that allows to get input from the user.

Inheritance

System.Object

SfBaseComponent

SfMaskedTextBox

Inherited Members

SfBaseComponent.Dispose()

SfBaseComponent.Dispose(Boolean)

SfBaseComponent.GetEffectivePlatform()

SfBaseComponent.GetMainComponentPlatform()

SfBaseComponent.IsMainLicenseComponent()

SfBaseComponent.LicenseContext

SfBaseComponent.OnAfterRenderAsync(Boolean)

SfBaseComponent.OnInitializedAsync()

SfBaseComponent.OnObservableChange(String, Object, Boolean, NotifyCollectionChangedEventArgs)

SfBaseComponent.ValidateLicense()

Namespace: Syncfusion.Blazor.Inputs

Assembly: Syncfusion.Blazor.dll

Syntax

public class SfMaskedTextBox : SfBaseComponent, IInputBase

Remarks

The SfMaskedTextBox component enables users to enter formatted input such as phone numbers, dates, social security numbers, and other structured data. It supports various mask characters, custom regular expressions, and provides real-time validation during input.

Examples

A simple MaskedTextBox component for phone number input.

<SfMaskedTextBox Mask="000-000-0000" Placeholder="Enter phone number" @bind-Value="@phoneNumber"></SfMaskedTextBox>

Constructors

SfMaskedTextBox()

Declaration

public SfMaskedTextBox()

Properties

Blur

Gets or sets the event callback that will be invoked when the SfMaskedTextBox loses focus.

Declaration

public EventCallback<MaskBlurEventArgs> Blur { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<MaskBlurEventArgs>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the component loses focus. The callback receives a MaskBlurEventArgs containing the event details.

Remarks

This event is triggered when the user moves focus away from the SfMaskedTextBox component, such as by clicking elsewhere or using keyboard navigation. You can use this event to perform validation, save data, or update other components when the user finishes interacting with the masked text input.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" Blur="@OnBlur">
</SfMaskedTextBox>
@code{
    private void OnBlur(MaskBlurEventArgs args)
    {
        // Handle blur event
        Console.WriteLine("MaskedTextBox lost focus");
    }
}

Created

Gets or sets the event callback that will be invoked when the SfMaskedTextBox component is created.

Declaration

public EventCallback<object> Created { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the component has been fully created and initialized. The callback receives an System.Object parameter.

Remarks

This event is triggered once during the component lifecycle, after the component has been instantiated and all its properties have been initialized. Use this event to perform initialization tasks that depend on the component being fully created, such as setting up additional event handlers or initializing related components. This event occurs before the component is first rendered in the DOM.

Examples

<SfMaskedTextBox Mask="000-00-0000" Created="@OnCreated">
</SfMaskedTextBox>
@code{
    private void OnCreated(object args)
    {
        // Component has been created
        Console.WriteLine("MaskedTextBox component created");
    }
}

CssClass

Gets or sets a CSS class string to customize the appearance of the component.

Declaration

public string CssClass { get; set; }

Property Value

Type	Description
System.String	Accepts a CSS class string separated by space to customize the appearance. The default value is String.Empty.

Remarks

The CssClass property allows you to apply custom styling to the SfMaskedTextBox component by adding CSS classes. Multiple CSS classes can be specified by separating them with spaces. These classes will be applied to the root element of the component.

Examples

<SfMaskedTextBox CssClass="custom-style highlight" Mask="(999) 000-0000">
</SfMaskedTextBox>

CustomCharacters

Gets or sets a collection of custom characters that can be used for non-mask elements(literals).

Declaration

public Dictionary<string, string> CustomCharacters { get; set; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.String>	A dictionary value of custom characters.

Remarks

The CustomCharacters property allows you to define additional special characters that can be used in the mask pattern. For example non-mask elements "P" accepts values "P" , "A" , "p" , "a" and "M" accepts values "M", "m" mentioned in the custom characters collection.

Examples

<SfMaskedTextBox Mask="00:00 >PM" CustomCharacters="@customMask">
</SfMaskedTextBox>
@code{
    private Dictionary<string, string> customMask = new Dictionary<string, string>()
    {
        {"P" , "P,p,A,a" },
        {"M" , "m,M" }
    }
}

Destroyed

Gets or sets the event callback that will be invoked when the SfMaskedTextBox component is destroyed.

Declaration

public EventCallback<object> Destroyed { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.Object>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the component is being destroyed and disposed. The callback receives an System.Object parameter.

Remarks

This event is triggered during the component lifecycle when the component is being removed from the DOM and disposed of. Use this event to perform cleanup tasks such as removing event listeners, disposing of resources, or saving final state information. This event occurs before the component is completely removed from memory and is the last opportunity to access component data.

Examples

<SfMaskedTextBox Mask="000-00-0000" Destroyed="@OnDestroyed">
</SfMaskedTextBox>
@code{
    private void OnDestroyed(object args)
    {
        // Perform cleanup
        Console.WriteLine("MaskedTextBox component destroyed");
    }
}

Enabled

Gets or sets a value that indicates whether to enable or disable the SfMaskedTextBox component.

Declaration

public bool Enabled { get; set; }

Property Value

Type	Description
System.Boolean	true, allows the user to interact with the component. Otherwise, false. The default value is true.

Remarks

When the Enabled property is set to false, the component becomes non-interactive and appears disabled. Users will not be able to focus, type, or interact with the masked text box. The component will also be excluded from tab navigation. This property is useful for conditionally enabling or disabling the component based on application state or user permissions.

Examples

<SfMaskedTextBox Enabled="false" Mask="(999) 000-0000" Value="(123) 456-7890">
</SfMaskedTextBox>

EnableLiterals

Gets or sets a value indicating whether literals are enabled in the masked text box.

Declaration

public bool EnableLiterals { get; set; }

Property Value

Type	Description
System.Boolean	true if literals are included in the Value; otherwise, false. The default value is false.

Remarks

When the EnableLiterals property is set to true, the mask pattern's literal characters (such as parentheses, spaces, and hyphens) are included in the Value property. For example, with the mask "(999) 000-0000" and user input "1234567890", the Value would be "(123) 456-7890" when literals are enabled, or "1234567890" when disabled. You can also retrieve the masked value using the GetMaskedValue method.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" EnableLiterals="true" @bind-Value="@maskValue">
</SfMaskedTextBox>
<p>Mask Value - @maskValue</p>
@code{
    private string maskValue = string.Empty;
}

EnablePersistence

Gets or sets whether to persist component's state between page reloads. When set to true, the Value property is persisted.

Declaration

public bool EnablePersistence { get; set; }

Property Value

Type	Description
System.Boolean	true, if the component's state persistence is enabled. The default value is false.

Remarks

Component's Value property will be stored in browser local storage to persist component's state when page reloads.

EnableRtl

Gets or sets whether the right-to-left direction is enabled or not for the component.

Declaration

public bool EnableRtl { get; set; }

Property Value

Type	Description
System.Boolean	true, if the right to left direction can be enabled for the component. Otherwise false. The default value is false.

Remarks

The EnableRtl property configures the text direction and layout orientation of the SfMaskedTextBox component. When enabled, the component will render with right-to-left text direction, which is suitable for languages like Arabic, Hebrew, and Persian. This affects the text alignment, cursor positioning, and overall component layout.

Examples

<SfMaskedTextBox EnableRtl="true" Mask="(999) 000-0000">
</SfMaskedTextBox>

FloatLabelType

Gets or sets the floating label behavior of the SfMaskedTextBox. The Placeholder text act as a lable.

Declaration

public FloatLabelType FloatLabelType { get; set; }

Property Value

Type	Description
FloatLabelType	One of the FloatLabelType enumeration. The default value is Never

Remarks

If the FloatLabelType is Never, the placeholder text does not float as a label. If the FloatLabelType is Auto, the placeholder text will float above the SfMaskedTextBox component as a label after focusing it. If the FloatLabelType is Always, the placeholder text is displayed as a label above the SfMaskedTextBox component.

Examples

In the following code example, set the float lable as Auto.

  <SfMaskedTextBox Placeholder="Enter phone number" FloatLabelType="FloatLabelType.Auto" Mask="(999) 000-0000">
  </SfMaskedTextBox>

Focus

Gets or sets the event callback that will be invoked when the SfMaskedTextBox gets focus.

Declaration

public EventCallback<MaskFocusEventArgs> Focus { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<MaskFocusEventArgs>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the component receives focus. The callback receives a MaskFocusEventArgs containing the event details.

Remarks

This event is triggered when the user sets focus to the SfMaskedTextBox component, such as by clicking on it or navigating to it using keyboard tabbing. You can use this event to perform actions when the user begins interacting with the component, such as highlighting related elements, showing help text, or preparing the component for input. The focus event occurs before the user begins typing or making changes to the component value.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" Focus="@OnFocus">
</SfMaskedTextBox>
@code{
    private void OnFocus(MaskFocusEventArgs args)
    {
        // Handle focus event
        Console.WriteLine("MaskedTextBox received focus");
    }
}

HtmlAttributes

Gets or sets a collection of additional attributes such as styles, class, and more that will be applied to the SfMaskedTextBox component.

Declaration

public Dictionary<string, object> HtmlAttributes { get; set; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.Object>	The value as dictionary collection.The default value is null

Remarks

If you configured both property and equivalent html attributes, then the component considers the property value.

Examples

<SfMaskedTextBox HtmlAttributes="@CustomAttribute" Mask="(999) 000-0000">
</SfMaskedTextBox>
@code{
    Dictionary<string, object> CustomAttribute = new Dictionary<string, object>()
    {
        { "title", "Please enter the phone number" }
    };
}

ID

Gets or sets the ID of the component.

Declaration

public string ID { get; set; }

Property Value

Type	Description
System.String	A string representing the identifier of the component.

Remarks

The ID property allows you to uniquely identify the component in the rendered HTML markup. If you don't set a custom ID, the component's ID will be auto-generated, and it may not be as descriptive as you require.

InputAttributes

Gets or sets a collection of additional inputs attributes such as disabled, value, and more that will be applied to the TextBox component.

Declaration

public Dictionary<string, object> InputAttributes { get; set; }

Property Value

Type	Description
System.Collections.Generic.Dictionary<System.String, System.Object>	The value as dictionary collection.The default value is null

Remarks

Additional attributes can be added by specifying as inline attributes or by specifying @attributes directive. If you configured both property and equivalent html attributes, then the component considers the property value.

Examples

<SfMaskedTextBox @attributes="@CustomAttribute" Mask="(999) 000-0000">
</SfMaskedTextBox>
@code{
    Dictionary<string, object> CustomAttribute = new Dictionary<string, object>()
    {
        { "type", "tel" }
    };
}

Mask

Gets or sets the mask pattern for the text input.

Declaration

public string Mask { get; set; }

Property Value

Type	Description
System.String	A string representing the mask pattern.

Remarks

The Mask property defines the pattern that the user's input must follow. It can include various special characters that define the allowed input format. For example, # might represent a digit and _ might represent an optional character. Literal characters included in the mask will be displayed as part of the mask.

Examples

<SfMaskedTextBox Mask="(999) 000-0000">
</SfMaskedTextBox>

Placeholder

Gets or sets the text that is displayed when the SfMaskedTextBox has no value and is removed on focus.

Declaration

public string Placeholder { get; set; }

Property Value

Type	Description
System.String	The text that is displayed when the SfMaskedTextBox has no value. The default value is String.Empty.

Remarks

The Placeholder property provides helpful guidance to users by showing example text or instructions when the input field is empty. The behavior of the placeholder depends on the FloatLabelType property. When FloatLabelType is set to Auto or Always, the placeholder text acts as a floating label. The placeholder text disappears when the user starts typing or when the component receives focus.

Examples

<SfMaskedTextBox Placeholder="Enter phone number" Mask="(999) 000-0000">
</SfMaskedTextBox>

PromptChar

Gets or sets the character used as a placeholder in the masked text box for unfilled positions.

Declaration

public char PromptChar { get; set; }

Property Value

Type	Description
System.Char	A character that indicates an unfilled position in the mask. The default value is _ (underscore).

Remarks

The PromptChar is displayed in the input field to visually represent the available positions where users can enter data according to the mask pattern. This character helps users understand the expected input format and the number of characters required. For example, with a phone number mask "(999) 000-0000" and the default prompt character, the field would initially display "()-____". The prompt character is replaced by user input as they type, providing immediate visual feedback about the input progress.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" PromptChar="*">
</SfMaskedTextBox>

PromptPlaceholder

Gets or sets the character that replaces the blank spaces in the Value property.

Declaration

public Nullable<char> PromptPlaceholder { get; set; }

Property Value

Type	Description
System.Nullable<System.Char>	A character value used to replace blank spaces. The default value is a space character.

Remarks

The PromptPlaceholder property is only effective when the EnableLiterals property is set to true. When literals are enabled, any unfilled positions in the mask that correspond to user input will be filled with this placeholder character in the final Value. This helps maintain the mask format while clearly indicating which positions were not filled by the user. If EnableLiterals is false, this property has no effect.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" EnableLiterals="true" @bind-Value="@maskValue" PromptPlaceholder="*">
</SfMaskedTextBox>
<p>Mask Value - @maskValue</p>
@code{
    private string maskValue = string.Empty;
}

Readonly

Gets or sets the boolean value whether the SfMaskedTextBox allows the user to change the text.

Declaration

public bool Readonly { get; set; }

Property Value

Type	Description
System.Boolean	true, if the SfMaskedTextBox component cannot be edited. Otherwise, false. The default value is false.

Remarks

When the Readonly property is set to true, the component becomes read-only, preventing users from modifying the text. However, unlike the Enabled property, a read-only component can still receive focus and participate in tab navigation. The existing value remains visible and can be selected and copied by users. This is useful for displaying data that should not be modified while still allowing user interaction for copying or viewing purposes.

Examples

<SfMaskedTextBox Readonly="true" Mask="(999) 000-0000" Value="(123) 456-7890">
</SfMaskedTextBox>

SfMaskedTextBoxEditContext

Specifies the edit context of MaskedTextBox component.

Declaration

protected EditContext SfMaskedTextBoxEditContext { get; set; }

Property Value

Type
Microsoft.AspNetCore.Components.Forms.EditContext

ShowClearButton

Gets or sets a value that indicates whether the clear button is displayed in the SfMaskedTextBox component.

Declaration

public bool ShowClearButton { get; set; }

Property Value

Type	Description
System.Boolean	true, if the clear button should be shown. Otherwise, false. The default value is false.

Remarks

When the ShowClearButton property is set to true, a clear button (typically an 'X' icon) appears on the right side of the input field. Clicking this button clears the entire content of the SfMaskedTextBox, setting the Value to an empty string. The clear button is only visible when the component has a value and is not disabled or read-only. This feature enhances user experience by providing a quick way to clear the input without manually selecting and deleting the content.

Examples

<SfMaskedTextBox ShowClearButton="true" Mask="(999) 000-0000">
</SfMaskedTextBox>

TabIndex

Gets or sets the tab order of the SfMaskedTextBox component.

Declaration

public int TabIndex { get; set; }

Property Value

Type	Description
System.Int32	An integer value representing the tab index of the component. The default value is 0.

Remarks

The TabIndex property determines the order in which the component receives focus when the user navigates using the Tab key. Components with lower tab index values receive focus before those with higher values. A value of -1 removes the component from the tab sequence, while 0 places it in the default tab order based on its position in the DOM. Positive values explicitly set the tab order priority.

Examples

<SfMaskedTextBox TabIndex="1" Mask="(999) 000-0000">
</SfMaskedTextBox>

Value

Gets or sets the current value of the masked text box.

Declaration

public string Value { get; set; }

Property Value

Type	Description
System.String	The input value of the masked text box.

Remarks

The Value property holds the current text entered into the masked text box. If EnableLiterals is set to true, literal characters included in the mask pattern will also be part of the Value. Otherwise, only the user-entered characters will be part of the Value.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" EnableLiterals=true @bind-Value="@maskValue">
</SfMaskedTextBox>
<p>Mask Value - @maskValue</p>
@code{
    private string maskValue{ get; set; }
}

ValueChange

Gets or sets the event callback that will be invoked when the content of SfMaskedTextBox has changed.

Declaration

public EventCallback<MaskChangeEventArgs> ValueChange { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<MaskChangeEventArgs>	An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the component's value changes. The callback receives a MaskChangeEventArgs containing the new value and event details.

Remarks

This event is triggered whenever the user modifies the content of the masked text box, including when characters are entered, deleted, or modified. The event provides access to both the raw value and the formatted value according to the specified mask pattern. This is the primary event for implementing data binding and handling user input changes in real-time.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" ValueChange="@OnChange">
</SfMaskedTextBox>
@code{
    private void OnChange(MaskChangeEventArgs args)
    {
        var TextValue = args.Value;
    }
}

ValueChanged

Gets or sets the callback to trigger when the value changes.

Declaration

public EventCallback<string> ValueChanged { get; set; }

Property Value

Type	Description
Microsoft.AspNetCore.Components.EventCallback<System.String>	An Microsoft.AspNetCore.Components.EventCallback<> of type System.String that is invoked when the component value changes.

Remarks

The ValueChanged event is triggered whenever the user modifies the text in the SfMaskedTextBox component. This includes changes made through typing, pasting, or using the clear button. The event provides the new value as a string parameter. This event is essential for two-way data binding and allows the parent component to respond to value changes in real-time. The event is fired after the value has been validated against the mask pattern.

Examples

<SfMaskedTextBox Mask="(999) 000-0000" @bind-Value="@phoneNumber" ValueChanged="@OnValueChanged">
</SfMaskedTextBox>
@code{
    private string phoneNumber = string.Empty;

    private void OnValueChanged(string value)
    {
        // Handle value change
        Console.WriteLine($"New value: {value}");
    }
}

Width

Gets or sets the width of the SfMaskedTextBox component.

Declaration

public string Width { get; set; }

Property Value

Type	Description
System.String	A string representing the width in pixels, percentage, or any valid CSS width value. The default value is null.

Remarks

The Width property allows you to control the horizontal size of the SfMaskedTextBox component. You can specify the width using various CSS units such as pixels (px), percentages (%), em, rem, or other valid CSS width values. When not specified, the component will use its default width behavior based on the applied styles and container constraints.

Examples

<SfMaskedTextBox Width="300px" Mask="(999) 000-0000">
</SfMaskedTextBox>

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration

protected override void BuildRenderTree(RenderTreeBuilder __builder)

Parameters

Type	Name	Description
Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder	__builder

FocusAsync()

Asynchronously sets the focus to the SfMaskedTextBox component to enable user interaction.

Declaration

public Task FocusAsync()

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task representing the asynchronous focus operation.

Remarks

This method programmatically sets focus to the MaskedTextBox input element, allowing the user to immediately start typing or interacting with the component. The focus operation is performed asynchronously through JavaScript interop to ensure proper DOM manipulation. Calling this method will trigger the focus event and any associated event handlers.

Examples

The following example demonstrates how to set focus to the MaskedTextBox component.

<SfMaskedTextBox @ref="maskedTextBoxRef" Mask="999-999-9999" />
<button @onclick="SetFocus">Focus MaskedTextBox</button>

@code {
    SfMaskedTextBox maskedTextBoxRef;

    private async Task SetFocus()
    {
        await maskedTextBoxRef.FocusAsync();
    }
}

FocusOutAsync()

Asynchronously removes the focus from the SfMaskedTextBox component if it is currently in focus state.

Declaration

public Task FocusOutAsync()

Returns

Type	Description
System.Threading.Tasks.Task	A System.Threading.Tasks.Task representing the asynchronous focus removal operation.

Remarks

This method programmatically removes focus from the MaskedTextBox input element, effectively blurring the component. The focus removal operation is performed asynchronously through JavaScript interop to ensure proper DOM manipulation. If the component is not currently focused, this method will have no effect. Calling this method will trigger the blur event and any associated event handlers.

Examples

The following example demonstrates how to remove focus from the MaskedTextBox component.

<SfMaskedTextBox @ref="maskedTextBoxRef" Mask="999-999-9999" />
<button @onclick="RemoveFocus">Remove Focus</button>

@code {
    SfMaskedTextBox maskedTextBoxRef;

    private async Task RemoveFocus()
    {
        await maskedTextBoxRef.FocusOutAsync();
    }
}

GetMaskedValue()

Gets the value of SfMaskedTextBox component with the respective mask literals applied.

Declaration

public string GetMaskedValue()

Returns

Type	Description
System.String	A string representing the current input value with mask literals included.

Remarks

This method returns the formatted value that includes both the user input and the mask literals (such as separators, symbols, or placeholder characters). The returned value represents the complete masked text as displayed to the user in the input field. Use this method when you need to retrieve the formatted display value rather than just the raw user input.

Examples

The following example demonstrates how to get the masked value from the MaskedTextBox component.

<SfMaskedTextBox @ref="maskedTextBoxRef" Mask="(999) 999-9999" Value="1234567890" />

@code {
    SfMaskedTextBox maskedTextBoxRef;

    private void GetFormattedValue()
    {
        string maskedValue = maskedTextBoxRef.GetMaskedValue(); // Returns "(123) 456-7890"
    }
}

GetPersistDataAsync()

Asynchronously retrieves the properties that are maintained in the persisted state from local storage.

Declaration

public Task<string> GetPersistDataAsync()

Returns

Type	Description
System.Threading.Tasks.Task<System.String>	A System.Threading.Tasks.Task<> of string containing the serialized persistent data, or null if no data exists.

Remarks

This method retrieves the component's persistent state data that was previously stored in the browser's local storage. The returned data contains the serialized properties that were configured to be persisted when the component's EnablePersistence property is enabled. The persistent data is stored using the component's ID as the key in local storage.

Examples

The following example demonstrates how to retrieve persistent data from the MaskedTextBox component.

<SfMaskedTextBox @ref="maskedTextBoxRef" ID="persistentMaskedTextBox" EnablePersistence="true" />
<button @onclick="GetPersistedData">Get Persisted Data</button>

@code {
    SfMaskedTextBox maskedTextBoxRef;

    private async Task GetPersistedData()
    {
        string persistedData = await maskedTextBoxRef.GetPersistDataAsync();
        // Use the retrieved persistent data as needed
    }
}