Numeric Masks

• Jul 31, 2024
• 8 minutes to read

Spin Edit and Masked Input components can use numeric masks. This means you can ensure that users can only enter integers, currency, percentage, or other numbers in a specific format. Our components support the following three methods to specify a mask:

• Built-in patterns. Select a mask from a few most frequently used types.
• Standard numeric .NET format strings. These format strings give you a wider format selection than the predefined templates.
• Custom masks. Build a custom mask expression if the methods above do not work.

Run Demo: Spin Edit — Mask Run Demo: Masked Input — Numeric Mask

Numeric masks impose the following requirements on editor value type:

• Set the DxSpinEdit.Value/DxMaskedInput.Value property to a numeric object.
• If you bind the Masked Input’s edit value to a non-numeric object, set MaskMode to MaskMode.Numeric.

For information on other mask types, refer to the following topic: Masks.

Apply a Mask

To apply a mask to the component, assign the required pattern (see the sections below) to the component’s Mask property (DxSpinEdit.Mask or DxMaskedInput.Mask). The DxNumericMaskProperties component specifies additional mask-related settings (for example, the current culture).

@using System.Globalization

<DxSpinEdit @bind-Value="Value"
            Mask="@NumericMask.Currency">
    <DxNumericMaskProperties Culture="Culture" />
</DxSpinEdit>

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

Note

Make sure the mask pattern fits the editor’s value type. For example, if an editor’s Value is of an integer type, the editor only accepts integer values. A user cannot enter a fractional part of a number, even if it is allowed by the editor’s mask.

Predefined Masks

If you apply a predefined mask pattern, the number format may depend on the current culture. For example, the currency mask produces different patterns in the U.S. and France. The currency symbol and the thousand separator may vary. You can use the NumberFormat property to change a culture-specific numeric format. Users can do the same in the Settings → Time & Language → Region system dialog.

The following mask patterns are supported:

Built-in Patterns

Use NumericMask properties to specify built-in patterns. Each property is a wrapper for the corresponding format string (see the section below). This approach simplifies the set up process for the users who are not familiar with the standard format strings.

<DxSpinEdit @bind-Value="Value" 
            Mask="@NumericMask.RealNumber">
</DxSpinEdit>

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

Standard Format Strings

Refer to the following article for more information on supported format strings: Standard numeric .NET format strings.

<DxSpinEdit @bind-Value="Value"
            Mask="n3">
</DxSpinEdit>

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

Specify a mask in the following format: Axx (for example, n4). The first part (A) is a single alphabetical character - the mask type specifier. The second part (xx) is an optional integer called the precision specifier. This value ranges from 0 to 99 and usually controls the number of significant digits or zeroes to the right of the decimal point. See the table below for a detailed syntax explanation.

Mask Specifiers

The following table lists available mask specifiers:

Predefined Pattern	.NET Format String	Description	Sample
Currency	C or c	Currencies. Users cannot edit the currency symbol. The NumberFormat property of the current culture specifies settings that affect how numeric values are displayed. The precision specifier (after a .NET format string) indicates the number of decimal places. If the precision specifier is omitted, the default currency precision declared in the NumberFormat object is used.	$12,345.67 (Mask=”c2”) $12,345 (Mask=”c0”)
WholeNumber	D or d	Whole numbers. The fraction part is discarded. The precision specifier indicates the maximum number of digits that can be entered. If the precision specifier is equal to 0 or omitted, the length of the input string is not limited.	12345
RealNumber	F or f G or g	Real numbers. The precision specifier indicates the number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat object is used.	12345.67
RealNumberWithThousandSeparator	N or n	Real numbers with thousand separators. The culture’s NumberDecimalDigits property specifies the number’s precision.	12,345.678 (Mask=”n3”)
Percentage	P	Percentage. Displays an editor value as is. The mask’s format is determined by the PercentNegativePattern and PercentPositivePattern properties, depending upon the sign of the entered number. The precision specifier indicates the number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat object is used.	12.00% (editor value is ”12”)
PercentageMultipliedBy100	p	Percentage. Multiplies an editor value by 100. The mask’s format is determined by the PercentNegativePattern and PercentPositivePattern properties, depending upon the sign of the entered number. The precision specifier indicates the number of decimal places. If the precision specifier is omitted, the default numeric precision declared in the NumberFormat object is used.	12.00% (editor value is “0.12”)

Custom Masks

If the predefined masks do not meet your requirements, use custom masks instead.

<DxSpinEdit @bind-Value="Value" 
            Mask="#,##0.00;<<#,##0.00>>">
</DxSpinEdit>

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

You can use any of the following characters to build custom numeric masks. For more information, refer to the following article: Custom numeric format strings.

Character	Description	Sample
#	An optional digit. A decimal digit (0-9) can be entered in the corresponding position or left empty. The empty placeholders are not displayed. When the input string is converted to the editor’s value, digits left empty are not stored in the result.	<empty> (“###”, editor value is 0) 1 (“###”, editor value is 1) 123 (“###”, editor value is 123)
0	A required digit. A decimal digit (0-9) can be entered in the corresponding position. Empty placeholders are treated as zeroes (0).	0 (“##0”, editor has no value) 1 (“##0”, editor value is 1) 123 (“##0”, editor value is 123)
.	Determines the location of the decimal separator in the formatted value. The actual character used as a decimal point separator is specified by the CultureInfo.NumberFormat.NumberDecimalSeparator property.	.1 (“#.#”, editor value is 0.1) 0.1 (“0.#”, editor value is 0.1) 0.100 (“0.000”, editor value is 0.1) 123.0 (“##0.0”, editor value is 123)
,	Group (thousand) separator. If the , character appears in the mask, thousand separators are inserted between each group of digits to the left of the decimal point as defined by the NumberFormat object. If the mask contains the $ symbol, the CurrencyGroupSeparator and CurrencyGroupSizes properties are used instead. If the mask contains the % symbol, the PercentGroupSizes and PercentGroupSeparator properties are used instead.	-1,234.50 (“#,##0.00”, editor value is -1234.5) 12,345 (“##,###”, editor value is 12345) 123 (“##,###”, editor value is 123)
%	Multiplies the percentage value by 100. The percent symbol is specified by the CultureInfo.NumberFormat.PercentSymbol property.	-12.34% (“#0.00%”, editor value is -0.1234)
%%	Displays the percentage value as is. The percent symbol is specified by the CultureInfo.NumberFormat.PercentSymbol property.	-12.34% (“#0.00%%”, editor value is -12.34) 0.12% (“#0.00%%”, editor value is 0.1234)
\	The character following the escape character is inserted into the edit box literally. To display a backslash in the edit box, use two backslashes (\\).	123.45% (“#0.00\%”, editor value is 123.45)
;	Allows you to set up different mask expressions for positive (left-hand expression) and negative (right-hand expression) values. If there is no expression after this placeholder, the editor does not allow users to enter negative values.	The “#,##0.00;<<#,##0.00>>” mask displays positive values as is, and encloses negative values in double angled brackets (“1,234.5” or “<<-1,234.5>>)”
$	Currency character. The currency symbol is specified by the NumberFormatInfo.CurrencySymbol property.	12 $ (“###0 $”)
Any other characters.	Any other characters are displayed in the edit box as is.

User Capabilities

Numeric masks allow users to enter numeric values only. Text cannot be edited in this mask mode.

• If a user edits the Masked Input component’s value and presses the minus key (-), the value sign changes. The caret can be anywhere in the edit box.
• If a user presses the Up/Down arrow keys in the Masked Input, the digit to the left of the caret position is incremented/decremented. If the entire value is selected or a user edits the Spin Edit value, these keys increment/decrement the digit to the left of the decimal point.
• If a user scrolls the mouse wheel and a Masked Input is focused, the digit to the left of the caret’s position is incremented/decremented. If the entire value is selected or a user focuses a Spin Edit, the mouse wheel increments/decrements the digit to the left of the decimal point.

User Scenarios

Integer Numbers

<DxSpinEdit @bind-Value="Value"
            Mask="@NumericMask.WholeNumber">
</DxSpinEdit>

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

The NumericMask.WholeNumber mask allows users to enter integer numbers only. The fraction part is discarded (even if the editor’s Value is bound to a non-integer type: Double or Decimal).

Numbers with X Decimal Places

<DxSpinEdit @bind-Value="Value"
            Mask="n3">
</DxSpinEdit>

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

The n3 mask allows users to enter three (or fewer) digits after a decimal point.

• Value is not entered:

  

• Value is entered:

  

Numbers with X Digits to the Left of the Decimal Point

<DxSpinEdit @bind-Value="Value"
            Mask="#,##0.00">
</DxSpinEdit>

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

The #,##0.00 mask allows users to enter four (or fewer) digits to the left of a decimal point and two (or fewer) digits after it.

Different Masks for Positive and Negative Numbers

<DxSpinEdit @bind-Value="Value"
            Mask="#,##0.00;<<#,##0.00>>">
</DxSpinEdit>

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

The #,##0.00;<<#,##0.00>> mask includes two parts divided by the ; sign.

• The left part (#,##0.00) specifies a mask for positive values.

  

• The right part (<<#,##0.00>>) - for negative values. This mask specifies that the negative values are enclosed with double angle brackets and the - sign is discarded.