syncfusion/wpf-ui-components-skills / skills/syncfusion-wpf-maskedtextbox
syncfusion-wpf-maskedtextbox
VerifiedComprehensive guide for implementing Syncfusion WPF MaskedTextBox (SfMaskedEdit) control for restricted input with mask patterns. Use this skill when implementing masked input, input masks, or input restrictions with predefined patterns in WPF. Covers phone number input, email validation, credit card input, formatted input with prompt characters, RegEx masks, and custom patterns for dates, currency, product keys, and zip codes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.0 KB |
| references/appearance-customization-themes.md | markdown | 6.5 KB |
| references/appearance-customization.md | markdown | 9.4 KB |
| references/getting-started.md | markdown | 9.6 KB |
| references/mask-patterns-advanced.md | markdown | 2.1 KB |
| references/mask-patterns-input-restriction.md | markdown | 14.2 KB |
| references/value-management-advanced.md | markdown | 5.4 KB |
| references/value-management.md | markdown | 11.2 KB |
references/value-management.md
View on GitHub# Value Management
This guide covers setting and retrieving values from SfMaskedEdit with different formatting options.
<!-- Table of contents removed for cross-environment compatibility; see section headings below -->
## Setting the Value Property
The `Value` property holds the current input of the SfMaskedEdit control. When you set a value, it's automatically formatted according to the mask.
### Basic Value Assignment
```xml
<syncfusion:SfMaskedEdit
Value="4553456789"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
x:Name="phoneInput"/>
```
```csharp
SfMaskedEdit phoneInput = new SfMaskedEdit();
phoneInput.Value = "4553456789";
phoneInput.MaskType = MaskType.RegEx;
phoneInput.Mask = @"\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}";
```
**Result:**
- **Input:** `"4553456789"`
- **Displayed:** `(455) 345-6789`
- **Value property:** Contains formatted text based on `ValueMaskFormat`
### Setting Value After Initialization
Set the `Value` property programmatically to update the control; the control reformats the value according to the mask (see examples above).
### Data Binding in MVVM
```xml
<syncfusion:SfMaskedEdit
Value="{Binding PhoneNumber, Mode=TwoWay}"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"/>
```
```csharp
public class ViewModel : INotifyPropertyChanged
{
private string _phoneNumber;
public string PhoneNumber
{
get => _phoneNumber;
set
{
_phoneNumber = value;
OnPropertyChanged(nameof(PhoneNumber));
}
}
public event PropertyChangedEventHandler PropertyChanged;
protected void OnPropertyChanged(string propertyName)
{
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName));
}
}
```
## Value Formatting Options
The `ValueMaskFormat` property controls what the `Value` property contains:
- User-entered characters only
- User-entered characters + literals
- User-entered characters + prompt characters
- User-entered characters + both literals and prompts
**Default:** `IncludePromptAndLiterals`
### ValueMaskFormat Enum Values
| Value | Description |
|-------|-------------|
| `ExcludePromptAndLiterals` | Only user-entered characters |
| `IncludeLiterals` | User characters + literals (no prompts) |
| `IncludePrompt` | User characters + prompts (no literals) |
| `IncludePromptAndLiterals` | User characters + literals + prompts (default) |
## ExcludePromptAndLiterals Format
Returns only the characters the user actually typed, excluding prompts and literals.
### Example: Phone Number
```xml
<syncfusion:SfMaskedEdit
ValueMaskFormat="ExcludePromptAndLiterals"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
Value="4553456789"
x:Name="phoneInput"/>
```
```csharp
SfMaskedEdit phoneInput = new SfMaskedEdit();
phoneInput.ValueMaskFormat = MaskFormat.ExcludePromptAndLiterals;
phoneInput.MaskType = MaskType.RegEx;
phoneInput.Mask = @"\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}";
phoneInput.Value = "4553456789";
// Display: (455) 345-6789
// Value property: "4553456789"
```
**What's included:**
- ✅ User-entered digits: `4553456789`
- ❌ Parentheses: `(` `)`
- ❌ Spaces
- ❌ Hyphen: `-`
### Use Cases
**Database Storage:**
```csharp
// Store clean data without formatting
private void SavePhone()
{
phoneInput.ValueMaskFormat = MaskFormat.ExcludePromptAndLiterals;
string cleanPhone = phoneInput.Value; // "4553456789"
// Save to database without literals
database.SavePhoneNumber(cleanPhone);
}
```
**API Submission:**
```csharp
// Send only digits to API
var request = new PhoneVerificationRequest
{
PhoneNumber = phoneInput.Value // "4553456789" without formatting
};
```
## IncludeLiterals Format
Returns user-entered characters plus literal characters defined in the mask. Excludes prompt characters for missing input.
### Example: Phone Number
```xml
<syncfusion:SfMaskedEdit
ValueMaskFormat="IncludeLiterals"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
Value="4553456789"
x:Name="phoneInput"/>
```
```csharp
phoneInput.ValueMaskFormat = MaskFormat.IncludeLiterals;
// Display: (455) 345-6789
// Value property: "(455) 345-6789"
```
**What's included:**
- ✅ User-entered digits: `4553456789`
- ✅ Parentheses: `(` `)`
- ✅ Spaces
- ✅ Hyphen: `-`
- ❌ Prompt characters (if input incomplete)
### Example: Partial Input
```csharp
// User enters: 455
// Display: (455) ___-____
// Value with IncludeLiterals: "(455) " (literals included, no prompts)
```
### Use Cases
**Display Formatted Value:**
```csharp
// Show formatted phone in UI
phoneInput.ValueMaskFormat = MaskFormat.IncludeLiterals;
string displayPhone = phoneInput.Value; // "(455) 345-6789"
messageTextBlock.Text = $"Your phone: {displayPhone}";
```
**Copy to Clipboard:**
```csharp
// Copy formatted value
Clipboard.SetText(phoneInput.Value); // "(455) 345-6789"
```
## IncludePrompt Format
Returns user-entered characters plus prompt characters for missing input. Excludes literals.
### Example: Phone Number
```xml
<syncfusion:SfMaskedEdit
ValueMaskFormat="IncludePrompt"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
PromptChar="_"
x:Name="phoneInput"/>
```
```csharp
phoneInput.ValueMaskFormat = MaskFormat.IncludePrompt;
phoneInput.PromptChar = '_';
// User enters: 455
// Display: (455) ___-____
// Value property: "455______" (no literals, includes prompts)
```
**What's included:**
- ✅ User-entered digits: `455`
- ✅ Prompt characters: `______` (for missing positions)
- ❌ Parentheses: `(` `)`
- ❌ Spaces
- ❌ Hyphen: `-`
### Example: Full Input
```csharp
// User enters: 4553456789
// Display: (455) 345-6789
// Value with IncludePrompt: "4553456789" (no literals, no prompts needed)
```
### Use Cases
**Check Completeness:**
```csharp
// Verify if all positions filled
phoneInput.ValueMaskFormat = MaskFormat.IncludePrompt;
bool isComplete = !phoneInput.Value.Contains('_');
if (isComplete)
{
// Process complete input
}
```
## IncludePromptAndLiterals Format
Returns everything: user-entered characters, literals, and prompt characters. This is the **default** format.
### Example: Phone Number
```xml
<syncfusion:SfMaskedEdit
ValueMaskFormat="IncludePromptAndLiterals"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
PromptChar="_"
x:Name="phoneInput"/>
```
```csharp
phoneInput.ValueMaskFormat = MaskFormat.IncludePromptAndLiterals; // Default
// User enters: 455
// Display: (455) ___-____
// Value property: "(455) ___-____" (everything included)
```
**What's included:**
- ✅ User-entered digits: `455`
- ✅ Parentheses: `(` `)`
- ✅ Spaces
- ✅ Hyphen: `-`
- ✅ Prompt characters: `___` (for missing positions)
### Example: Full Input
```csharp
// User enters: 4553456789
// Display: (455) 345-6789
// Value with IncludePromptAndLiterals: "(455) 345-6789"
```
### Use Cases
**Exact Display Representation:**
```csharp
// Get exactly what's shown in the control
string exactDisplay = phoneInput.Value; // "(455) ___-____"
```
## Format Comparison Table
Given mask: `\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}` and input: `455`
| Format | Value Property | Use Case |
|--------|----------------|----------|
| ExcludePromptAndLiterals | `"455"` | Database storage, API calls |
| IncludeLiterals | `"(455) "` | Display formatting, partial input |
| IncludePrompt | `"455______"` | Completeness checking |
| IncludePromptAndLiterals | `"(455) ___-____"` | Exact display representation |
Given complete input: `4553456789`
| Format | Value Property |
|--------|----------------|
| ExcludePromptAndLiterals | `"4553456789"` |
| IncludeLiterals | `"(455) 345-6789"` |
| IncludePrompt | `"4553456789"` |
| IncludePromptAndLiterals | `"(455) 345-6789"` |
## Value Change Notifications
Subscribe to the `ValueChanged` event to respond when the value changes.
### Basic Event Subscription
```xml
<syncfusion:SfMaskedEdit
ValueChanged="SfMaskedEdit_ValueChanged"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
x:Name="phoneInput"/>
```
```csharp
private void SfMaskedEdit_ValueChanged(object sender, EventArgs e)
{
var maskedEdit = sender as SfMaskedEdit;
string currentValue = maskedEdit.Value;
MessageBox.Show($"Value changed to: {currentValue}");
}
```
### When Does ValueChanged Fire?
The timing depends on the `ValidationMode` property:
#### With KeyPress Validation (Default)
```xml
<syncfusion:SfMaskedEdit
ValidationMode="KeyPress"
ValueChanged="OnValueChanged"/>
```
- Fires after **each valid keystroke**
- Value is updated immediately
- Invalid keystrokes don't trigger the event
#### With LostFocus Validation
```xml
<syncfusion:SfMaskedEdit
ValidationMode="LostFocus"
ValueChanged="OnValueChanged"/>
```
- Fires when **control loses focus**
- Only fires if validation succeeds
- Value is updated only after focus loss
### Example: Real-time Validation
```xml
<StackPanel>
<syncfusion:SfMaskedEdit
x:Name="phoneInput"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
ValueMaskFormat="ExcludePromptAndLiterals"
ValueChanged="PhoneInput_ValueChanged"/>
<TextBlock x:Name="statusText" Margin="0,5,0,0"/>
</StackPanel>
```
```csharp
private void PhoneInput_ValueChanged(object sender, EventArgs e)
{
var maskedEdit = sender as SfMaskedEdit;
if (!maskedEdit.HasError && maskedEdit.Value.Length == 10)
{
statusText.Text = "✓ Valid phone number";
statusText.Foreground = Brushes.Green;
}
else
{
statusText.Text = "Enter 10 digits";
statusText.Foreground = Brushes.Gray;
}
}
```
### Example: Sync Two Controls
```xml
<StackPanel>
<TextBlock Text="Enter phone number:"/>
<syncfusion:SfMaskedEdit
x:Name="phoneInput"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
ValueMaskFormat="IncludeLiterals"
ValueChanged="PhoneInput_ValueChanged"/>
<TextBlock Text="Formatted preview:" Margin="0,10,0,0"/>
<TextBox x:Name="previewText" IsReadOnly="True"/>
</StackPanel>
```
```csharp
private void PhoneInput_ValueChanged(object sender, EventArgs e)
{
previewText.Text = phoneInput.Value;
}
```
### Example: Multi-field Form Validation
```xml
<StackPanel>
<syncfusion:SfMaskedEdit
x:Name="phoneInput"
Mask="\([0-9]\d{2}\) [0-9]\d{2}-[0-9]\d{3}"
MaskType="RegEx"
ValueChanged="ValidateForm"/>
<syncfusion:SfMaskedEdit
x:Name="zipInput"
Mask="\d{5}-\d{4}"
MaskType="RegEx"
ValueChanged="ValidateForm"
Margin="0,10,0,0"/>
<Button x:Name="submitButton" Content="Submit" IsEnabled="False" Margin="0,10,0,0"/>
</StackPanel>
```
```csharp
private void ValidateForm(object sender, EventArgs e)
{
bool phoneValid = !phoneInput.HasError && !string.IsNullOrWhiteSpace(phoneInput.Value);
bool zipValid = !zipInput.HasError && !string.IsNullOrWhiteSpace(zipInput.Value);
submitButton.IsEnabled = phoneValid && zipValid;
}
```
## Clipboard Operations
### Copy Formatted Value
The clipboard behavior is affected by `ValueMaskFormat`:
<!-- Advanced value-change and clipboard examples moved to value-management-advanced.md -->
```csharp
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |