# MaskedTextBox

Namespace: **Wisej.Web**

Assembly: **Wisej.Framework** (4.0.0.0)

* [Control](/api/wisej.web/general/control.md)
  * [TextBoxBase](/api/wisej.web/editors/wisej.web.textboxbase.md)
    * [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md)

Uses a mask to distinguish between proper and improper user input.

{% tabs %}
{% tab title="C#" %}

```csharp
public class MaskedTextBox : TextBoxBase
```

{% endtab %}

{% tab title="VB.NET" %}

```visual-basic
Public Class MaskedTextBox
    Inherits TextBoxBase
```

{% endtab %}
{% endtabs %}

The MaskedTextBox class is an enhanced [TextBox](/api/wisej.web/editors/wisej.web.textbox.md) control that supports a declarative syntax for accepting or rejecting user input. Using the [Mask](#mask) property, you can enforce the following input types without writing any custom validation logic in your application:

* Required input characters.
* Optional input characters.
* The type of input expected at a given position in the mask; for example, a digit, or an alphabetic or alphanumeric character.
* Mask literals, or characters that should appear directly in the MaskedTextBox; for example, the hyphens(-) in a phone number, or the currency symbol in a price.
* Special processing for input characters; for example, to convert alphabetic characters to uppercase.
* Special processing for input characters; for example, to convert alphabetic characters to uppercase.

When a [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) control is displayed at run time, it represents the mask as a series of prompt characters and optional literal characters. Each editable mask position, representing a required or optional input, is shown with a single prompt character. For example, the number sign (#) is often used as a placeholder for a numeric character input. You can use the [PromptChar](#promptchar) property to specify a custom prompt character. The [HidePromptOnLeave](#hidepromptonleave) property determines if the user sees the prompt characters when the control loses input focus

## Constructors

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskedTextBox()

Initializes a new instance of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) class using defaults.

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskedTextBox(onTextChanged)

Initializes a new instance of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) class with specific initial settings.

| Name              | Type                                                                                | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **onTextChanged** | [Action\<Object, EventArgs>](https://docs.microsoft.com/dotnet/api/system.action-2) | Handler for the [TextChanged](/api/wisej.web/general/control.md#textchanged) event. |

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskedTextBox(mask, onTextChanged)

Initializes a new instance of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) class with specific initial settings.

| Name              | Type                                                                                | Description                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| **mask**          | [String](https://docs.microsoft.com/dotnet/api/system.string)                       | Initial [Mask](#mask).                                                              |
| **onTextChanged** | [Action\<Object, EventArgs>](https://docs.microsoft.com/dotnet/api/system.action-2) | Handler for the [TextChanged](/api/wisej.web/general/control.md#textchanged) event. |

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskedTextBox(label, mask, onTextChanged)

Initializes a new instance of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) class with specific initial settings.

| Name              | Type                                                                                | Description                                                                                        |
| ----------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **label**         | [String](https://docs.microsoft.com/dotnet/api/system.string)                       | The initial text to display in the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) label. |
| **mask**          | [String](https://docs.microsoft.com/dotnet/api/system.string)                       | The initial [Mask](#mask) value.                                                                   |
| **onTextChanged** | [Action\<Object, EventArgs>](https://docs.microsoft.com/dotnet/api/system.action-2) | Handler for the [TextChanged](/api/wisej.web/general/control.md#textchanged) event.                |

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskedTextBox(location, size, onTextChanged)

Initializes a new instance of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) class with specific initial settings.

| Name              | Type                                                                                | Description                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **location**      | [Point](https://docs.microsoft.com/dotnet/api/system.drawing.point)                 | The location of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) on its parent control. |
| **size**          | [Size](https://docs.microsoft.com/dotnet/api/system.drawing.size)                   | The size of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md).                           |
| **onTextChanged** | [Action\<Object, EventArgs>](https://docs.microsoft.com/dotnet/api/system.action-2) | Handler for the [TextChanged](/api/wisej.web/general/control.md#textchanged) event.                 |

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskedTextBox(label, mask, location, size, onTextChanged)

Initializes a new instance of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) class with specific initial settings.

| Name              | Type                                                                                | Description                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **label**         | [String](https://docs.microsoft.com/dotnet/api/system.string)                       | The initial text to display in the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) label.  |
| **mask**          | [String](https://docs.microsoft.com/dotnet/api/system.string)                       | The initial [Mask](#mask) value.                                                                    |
| **location**      | [Point](https://docs.microsoft.com/dotnet/api/system.drawing.point)                 | The location of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) on its parent control. |
| **size**          | [Size](https://docs.microsoft.com/dotnet/api/system.drawing.size)                   | The size of the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md).                           |
| **onTextChanged** | [Action\<Object, EventArgs>](https://docs.microsoft.com/dotnet/api/system.action-2) | Handler for the [TextChanged](/api/wisej.web/general/control.md#textchanged) event.                 |

## Properties

### ![](/files/hsR4ok3152WyAf8J2C1u) CharacterCasing

[CharacterCasing](/api/wisej.web/editors/wisej.web.charactercasing.md): Returns or sets whether the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) control modifies the case of characters as they are typed. (Default: `Normal`)

### ![](/files/hsR4ok3152WyAf8J2C1u) Culture

[CultureInfo](https://docs.microsoft.com/dotnet/api/system.globalization.cultureinfo): Returns or sets the culture information associated with the masked text box.

### ![](/files/hsR4ok3152WyAf8J2C1u) Filter

[String](https://docs.microsoft.com/dotnet/api/system.string): Returns or sets a JavaScript regular expression that limits the characters that the user can type. (Default: `null`)

### ![](/files/hsR4ok3152WyAf8J2C1u) HidePromptOnLeave

[Boolean](https://docs.microsoft.com/dotnet/api/system.boolean): Returns or sets whether the prompt characters in the input mask are hidden when the masked text box loses focus. (Default: `False`)

### ![](/files/hsR4ok3152WyAf8J2C1u) InputType

[InputType](/api/wisej.web/editors/wisej.web.inputtype.md): Specifies the type, min, max and step properties to associate to the \<input> element.

The default value is an InputType with Type=Text, Mode=Text.

### ![](/files/hsR4ok3152WyAf8J2C1u) Mask

[String](https://docs.microsoft.com/dotnet/api/system.string): Returns or sets the input mask. (Default: `""`)

The [Mask](#mask) is a string that defines the masking characters and the literals to display and process during user input and when reading the [Text](#text) property. Server side masking is processed by an instance of the [MaskedTextProvider](https://docs.microsoft.com/dotnet/api/system.componentmodel.maskedtextprovider) class exposed by the [MaskedTextProvider](#maskedtextprovider) property. On the client side, the mask processing is performed by the "wisej.utils.MaskProvider.js" class while the user edits the input field.

| Masking Character | Description                                                                                                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0                 | Digit, required. This element will accept any single digit between 0 and 9.                                                                                                                   |
| 9                 | Digit or space, optional.                                                                                                                                                                     |
| #                 | Digit or space, optional. If this position is blank in the mask, it will be rendered as a space in the Text property. Plus (+) and minus (-) signs are allowed.                               |
| L                 | Letter, required. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to \[a-zA-Z] in regular expressions.                                                      |
| ?                 | Letter, optional. Restricts input to the ASCII letters a-z and A-Z. This mask element is equivalent to \[a-zA-Z]? in regular expressions.                                                     |
| &                 | Character, required. This element behaves like the "L" element.                                                                                                                               |
| C                 | Character, optional. Any non-control character. This element behaves like the "?" element.                                                                                                    |
| A                 | Alphanumeric, required. The only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the "a" element.                                                 |
| a                 | Alphanumeric, optional. The only characters it will accept are the ASCII letters a-z and A-Z. This mask element behaves like the "A" element.                                                 |
| .                 | Decimal placeholder. The actual display character used will be the decimal symbol appropriate to the format provider, as determined by the control's FormatProvider property.                 |
| ,                 | Thousands placeholder. The actual display character used will be the thousands placeholder appropriate to the format provider, as determined by the control's FormatProvider property.        |
| :                 | Time separator. The actual display character used will be the time symbol appropriate to the format provider, as determined by the control's FormatProvider property.                         |
| /                 | Date separator. The actual display character used will be the date symbol appropriate to the format provider, as determined by the control's FormatProvider property.                         |
| $                 | Currency symbol. The actual character displayed will be the currency symbol appropriate to the format provider, as determined by the control's FormatProvider property.                       |
| <                 | Shift down. Converts all characters that follow to lowercase.                                                                                                                                 |
| >                 | Shift up. Converts all characters that follow to uppercase.                                                                                                                                   |
|                   |                                                                                                                                                                                               |
| \\                | Escape. Escapes a mask character, turning it into a literal. "\\" is the escape sequence for a backslash.                                                                                     |
| Others            | Literals. All non-mask elements will appear as themselves within MaskedTextBox. Literals always occupy a static position in the mask at run time, and cannot be moved or deleted by the user. |

If you change the [Mask](#mask) when the control already contains a value, it will apply the new mask to the existing text. The decimal (.), thousand (,), time (:), date (/), and currency ($) symbols default to displaying those symbols as defined by the application's culture. You can force a specific [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) to display symbols for another culture by using the [Culture](#culture) property. Otherwise you can set the application-wide culture by setting the [CurrentCulture](/api/wisej.web/general/application.md#currentculture) property.

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskedTextProvider

[MaskedTextProvider](https://docs.microsoft.com/dotnet/api/system.componentmodel.maskedtextprovider): Returns the mask provider associated with this instance of the masked text box control.

### ![](/files/hsR4ok3152WyAf8J2C1u) PasswordChar

[Char](https://docs.microsoft.com/dotnet/api/system.char): Returns or sets the character used to mask characters of a password in a single-line [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) control. (Default: `"\0"`)

This property only enables/disables the password mode for the textbox. It doesn't change the password masking character used by the browser.

### ![](/files/hsR4ok3152WyAf8J2C1u) PromptChar

[Char](https://docs.microsoft.com/dotnet/api/system.char): Returns or sets the character used to represent the absence of user input in the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) control. (Default: `_`)

**Throws:**

* [ArgumentException](https://docs.microsoft.com/dotnet/api/system.argumentexception) The character specified when setting this property is not a valid prompt character.

### ![](/files/hsR4ok3152WyAf8J2C1u) RejectInputOnFirstFailure

[Boolean](https://docs.microsoft.com/dotnet/api/system.boolean): Returns or sets whether the parsing of input text should stop after the first invalid character is reached. (Default: `False`)

### ![](/files/hsR4ok3152WyAf8J2C1u) SpellCheck

[Boolean](https://docs.microsoft.com/dotnet/api/system.boolean): Returns or sets whether the text in the [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) is spell checked by the browser. (Default: `False`)

### ![](/files/hsR4ok3152WyAf8J2C1u) Text

[String](https://docs.microsoft.com/dotnet/api/system.string): Returns or sets the current text in the text box. (Default: `""`)

### ![](/files/hsR4ok3152WyAf8J2C1u) TextAlign

[HorizontalAlignment](/api/wisej.web/enumerations/wisej.web.horizontalalignment.md): Returns or sets how text is aligned in a [TextBox](/api/wisej.web/editors/wisej.web.textbox.md) control. (Default: `Left`)

### ![](/files/hsR4ok3152WyAf8J2C1u) TextLength

[Int32](https://docs.microsoft.com/dotnet/api/system.int32): Returns the length of text in the control.

### ![](/files/hsR4ok3152WyAf8J2C1u) TextMaskFormat

[MaskFormat](/api/wisej.web/enumerations/wisej.web.maskformat.md): Returns or sets a value that determines whether literals and prompt characters are included in the formatted string. (Default: `IncludeLiterals`)

### ![](/files/hsR4ok3152WyAf8J2C1u) ValidatingType

[Type](https://docs.microsoft.com/dotnet/api/system.type): Returns or sets the data type used to verify the data input by the user. (Default: `null`)

## Methods

### ![](/files/lzopMboA31bVq8UIcbT3) MaskText(text)

Applies the mask to the text.

| Parameter | Type                                                          | Description   |
| --------- | ------------------------------------------------------------- | ------------- |
| **text**  | [String](https://docs.microsoft.com/dotnet/api/system.string) | Text to mask. |

**Returns:** [String](https://docs.microsoft.com/dotnet/api/system.string). Masked text.

### ![](/files/lzopMboA31bVq8UIcbT3) OnCultureChanged(e)

Fires the [CultureChanged](#culturechanged) event.

| Parameter | Type                                                                | Description                                                                                      |
| --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **e**     | [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) | An [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) that contains event data. |

### ![](/files/lzopMboA31bVq8UIcbT3) OnMaskChanged(e)

Fires the [MaskChanged](#maskchanged) event.

| Parameter | Type                                                                | Description                                                                                      |
| --------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **e**     | [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) | An [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) that contains event data. |

### ![](/files/lzopMboA31bVq8UIcbT3) OnTextAlignChanged(e)

Fires the [TextAlignChanged](/api/wisej.web/editors/wisej.web.textbox.md#textalignchanged) event.

| Parameter | Type                                                                | Description                                                                                         |
| --------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **e**     | [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) | A [EventArgs](https://docs.microsoft.com/dotnet/api/system.eventargs) that contains the event data. |

### ![](/files/lzopMboA31bVq8UIcbT3) OnTypeValidationCompleted(e)

Fires the [TypeValidationCompleted](#typevalidationcompleted) event.

| Parameter | Type                                                                                                 | Description                                                                                                                           |
| --------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **e**     | [TypeValidationEventArgs](/api/wisej.web/editors/maskedtextbox/wisej.web.typevalidationeventargs.md) | An [TypeValidationEventArgs](/api/wisej.web/editors/maskedtextbox/wisej.web.typevalidationeventargs.md) that contains the event data. |

### ![](/files/lzopMboA31bVq8UIcbT3) OnValidating(e)

Fires the [Validating](/api/wisej.web/general/control.md#validating) event.

| Parameter | Type                                                                                           | Description                                                                                                                |
| --------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **e**     | [CancelEventArgs](https://docs.microsoft.com/dotnet/api/system.componentmodel.canceleventargs) | A [CancelEventArgs](https://docs.microsoft.com/dotnet/api/system.componentmodel.canceleventargs) that contains event data. |

**Throws:**

* [Exception](https://docs.microsoft.com/dotnet/api/system.exception) A critical exception occurred during the parsing of the input string.

### ![](/files/lzopMboA31bVq8UIcbT3) OnWebRender(config)

Renders the client component.

| Parameter  | Type                                                          | Description                   |
| ---------- | ------------------------------------------------------------- | ----------------------------- |
| **config** | [Object](https://docs.microsoft.com/dotnet/api/system.object) | Dynamic configuration object. |

### ![](/files/lzopMboA31bVq8UIcbT3) UnmaskText(text)

Removes the mask from the text.

| Parameter | Type                                                          | Description     |
| --------- | ------------------------------------------------------------- | --------------- |
| **text**  | [String](https://docs.microsoft.com/dotnet/api/system.string) | Text to unmask. |

**Returns:** [String](https://docs.microsoft.com/dotnet/api/system.string). Unmasked text.

### ![](/files/hsR4ok3152WyAf8J2C1u) ValidateText()

Converts the user input string to an instance of the validating type.

**Returns:** [Object](https://docs.microsoft.com/dotnet/api/system.object). If successful, an [Object](https://docs.microsoft.com/dotnet/api/system.object) of the type specified by the [ValidatingType](#validatingtype) property; otherwise, null to indicate conversion failure.

**Throws:**

* [Exception](https://docs.microsoft.com/dotnet/api/system.exception) A critical exception occurred during the parsing of the input string.

## Events

### ![](/files/hsR4ok3152WyAf8J2C1u) CultureChanged

[EventHandler](https://docs.microsoft.com/dotnet/api/system.eventhandler) Fired when the value of the [Culture](#culture) property has changed.

### ![](/files/hsR4ok3152WyAf8J2C1u) MaskChanged

[EventHandler](https://docs.microsoft.com/dotnet/api/system.eventhandler) Fired when the value of the [Mask](#mask) property has changed.

### ![](/files/hsR4ok3152WyAf8J2C1u) TextAlignChanged

[EventHandler](https://docs.microsoft.com/dotnet/api/system.eventhandler) Fired when the value of the [TextAlign](#textalign) property has changed.

### ![](/files/hsR4ok3152WyAf8J2C1u) TypeValidationCompleted

[TypeValidationEventHandler](/api/wisej.web/editors/maskedtextbox/wisej.web.typevalidationeventhandler.md) Occurs when [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) has finished parsing the current value using the [ValidatingType](#validatingtype) property.

## Inherited By

| Name                                                                                                                                        | Description                                                                                                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [DataGridViewMaskedTextBoxEditingControl](/api/wisej.web/lists-and-grids/datagridview/wisej.web.datagridviewmaskedtextboxeditingcontrol.md) | Represents a [MaskedTextBox](/api/wisej.web/editors/maskedtextbox.md) control that can be hosted in a [DataGridViewMaskedTextBoxCell](/api/wisej.web/lists-and-grids/datagridview/wisej.web.datagridviewmaskedtextboxcell.md) cell. |

## Implements

| Name                                                                              | Description                                                                                                                                                                                                                                     |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [IUserData](/api/wisej.web/interfaces/wisej.web.iuserdata.md)                     | Provides access to the `UserData` and `Tag` properties associated to the component implementing this interface.                                                                                                                                 |
| [IBindableComponent](/api/wisej.web/data-binding/wisej.web.ibindablecomponent.md) | Bindable components implement this interface.                                                                                                                                                                                                   |
| [IDropTarget](/api/wisej.web/interfaces/wisej.web.idroptarget.md)                 | Controls that support drag & drop operations implement this interface.                                                                                                                                                                          |
| [ILabel](/api/wisej.web/interfaces/wisej.web.ilabel.md)                           | Provides access to the [LabelWrapper](/api/wisej.web/editors/wisej.web.labelwrapper.md) associated with the controls that implement this interface.                                                                                             |
| [IReadOnly](/api/wisej.web/interfaces/wisej.web.ireadonly.md)                     | Provides access to the [ReadOnly](/api/wisej.web/interfaces/wisej.web.ireadonly.md#readonly) property for coontrols that support the read-only mode.                                                                                            |
| [IModified](/api/wisej.web/interfaces/wisej.web.imodified.md)                     | Provides access to the [Modified](/api/wisej.web/interfaces/wisej.web.imodified.md#modified) property and [ModifiedChanged](/api/wisej.web/interfaces/wisej.web.imodified.md#modifiedchanged) event for controls that implement this interface. |
| [IValidation](/api/wisej.web/interfaces/wisej.web.ivalidation.md)                 | Provides access to the validation events and properties property for controls that support validation.                                                                                                                                          |
| [IWisejComponent](/api/wisej.core/interfaces/wisej.core.iwisejcomponent.md)       | All wisej components implement this interface.                                                                                                                                                                                                  |
| [IWisejControl](/api/wisej.core/interfaces/wisej.core.iwisejcontrol.md)           | All wisej controls derived from the [Control](/api/wisej.web/general/control.md) class must implement this interface.                                                                                                                           |
| [IWisejSerializable](/api/wisej.core/interfaces/wisej.core.iwisejserializable.md) | Allows an object to serialize itself.                                                                                                                                                                                                           |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wisej.com/api/wisej.web/editors/maskedtextbox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.