Class SfNumericTextBox<TValue>

The NumericTextBox is used to get the number inputs from the user. The input values can be incremented or decremented by a predefined step value.

Inheritance
object
ComponentBase
OwningComponentBase
SfOwningComponentBase
SfBaseComponent
SfInputTextBase<TValue>
SfNumericTextBox<TValue>
Implements
Inherited Members
Namespace: Syncfusion.Blazor.Inputs
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfNumericTextBox<TValue> : SfInputTextBase<TValue>, IComponent, IHandleEvent, IHandleAfterRender, IDisposable
Type Parameters
Name Description
TValue

Specifies the generic type of the SfNumericTextBox<TValue> component. This type determines the data type of the numeric value that can be entered and processed by the component.
Remarks

The SfNumericTextBox<TValue> component provides a user-friendly interface for numeric input with features like spin buttons, validation, formatting, and culture-specific number display. It supports various numeric types including int, double, decimal, float, and their nullable counterparts.

Examples

A simple NumericTextBox component.

<SfNumericTextBox TValue="int" Value="10" Min="0" Max="100" Step="1"></SfNumericTextBox>

Constructors

SfNumericTextBox()

Declaration
public SfNumericTextBox()

Properties

BaseFloatLabelType

Gets or sets the floating label behavior of the input component that determines how the placeholder text is displayed.

Declaration
protected override FloatLabelType BaseFloatLabelType { get; set; }
Property Value
Type Description
FloatLabelType

A FloatLabelType enumeration value that specifies the floating label behavior. The default value depends on the specific input component implementation.
Overrides
Remarks

The floating label behavior controls how the placeholder text is presented to the user:

  • NeverThe label never floats and remains as a standard placeholder text within the input field.
  • AlwaysThe label is always positioned above the input field, providing a consistent visual layout.
  • AutoThe label dynamically floats above the input field when the component receives focus or contains a value, creating an animated transition effect.

BaseHtmlAttributes

Gets or sets additional HTML attributes to be applied to the input component's container element.

Declaration
protected override Dictionary<string, object>? BaseHtmlAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A Dictionary<TKey, TValue> containing key-value pairs of HTML attributes, or null if no additional attributes are specified.
Overrides
Remarks

Use this property to add custom HTML attributes such as data attributes, accessibility attributes, or styling classes to the component's container. Common attributes like 'class', 'style', and 'title' are handled specially and may be applied to different elements within the component structure.

BaseInputAttributes

Gets or sets additional HTML attributes to be applied specifically to the input element itself.

Declaration
protected override Dictionary<string, object> BaseInputAttributes { get; set; }
Property Value
Type Description
Dictionary<string, object>

A Dictionary<TKey, TValue> containing key-value pairs of HTML attributes. The default value is an empty dictionary.
Overrides
Remarks

This property allows direct customization of the underlying input element with additional HTML attributes. Attributes set here will be applied directly to the input tag, enabling fine-grained control over input behavior and appearance.

BaseIsReadOnlyInput

Gets or sets a value indicating whether the input element itself should be marked as read-only.

Declaration
protected override bool BaseIsReadOnlyInput { get; set; }
Property Value
Type Description
bool

true if the input element is read-only; otherwise, false. The default value depends on the specific input component implementation.
Overrides
Remarks

This property specifically controls the read-only attribute on the underlying HTML input element, which may behave differently from the component-level BaseReadonly property.

BasePlaceholder

Gets or sets the placeholder text displayed in the input when no value is present.

Declaration
protected override string? BasePlaceholder { get; set; }
Property Value
Type Description
string

A string representing the placeholder text, or null if no placeholder is specified.
Overrides
Remarks

The placeholder provides a hint to users about the expected input format or content. This text is automatically hidden when the input receives focus or contains a value.

BaseReadonly

Gets or sets a value indicating whether the input component is in read-only mode.

Declaration
protected override bool BaseReadonly { get; set; }
Property Value
Type Description
bool

true if the input is read-only; otherwise, false. The default value depends on the specific input component implementation.
Overrides
Remarks

When in read-only mode, users can view and select the content but cannot modify it. The input will still receive focus and trigger events, but user input will be prevented.

BaseShowClearButton

Gets or sets a value indicating whether a clear button should be displayed to allow users to quickly clear the input value.

Declaration
protected override bool BaseShowClearButton { get; set; }
Property Value
Type Description
bool

true if the clear button should be shown; otherwise, false. The default value depends on the specific input component implementation.
Overrides
Remarks

When enabled, a clear button appears within the input field when it contains a value, allowing users to quickly clear the content. The button is automatically hidden when the input is empty, disabled, or read-only.

BaseTabIndex

Gets or sets the tab index of the input component for keyboard navigation.

Declaration
protected override int BaseTabIndex { get; set; }
Property Value
Type Description
int

An integer representing the tab order. Positive values indicate the explicit tab order, 0 means the element is focusable in document order, and negative values remove the element from tab navigation.
Overrides
Remarks

This property controls the order in which the component receives focus during keyboard navigation. When the component is disabled, the tab index is automatically set to -1 to remove it from the tab sequence.

BaseWidth

Gets or sets the width of the input component.

Declaration
protected override string? BaseWidth { get; set; }
Property Value
Type Description
string

A string representing the width in CSS units (e.g., "100px", "50%"), or null to use the default width.
Overrides
Remarks

This property accepts any valid CSS width value including pixels, percentages, em units, etc. The width is applied to the component's container element to control the overall size.

Currency

Gets or sets the currency code to use in currency formatting. Possible values are the ISO 4217 currency codes, such as USD for the US dollar and EUR for the euro.

Declaration
[Parameter]
public string Currency { get; set; }
Property Value
Type Description
string

A string value representing the ISO 4217 currency code. The default value is null.
Remarks

This property enables currency formatting for the numeric values displayed in the SfNumericTextBox<TValue>. When set, the component will format numbers according to the specified currency's conventions. Common examples include "USD" for US Dollar, "EUR" for Euro, "GBP" for British Pound, etc.

Examples
<SfNumericTextBox TValue="decimal?" Currency="USD" Placeholder="Enter amount">
</SfNumericTextBox>

Decimals

Gets or sets the number of decimal places to display for numeric values.

Declaration
[Parameter]
public int? Decimals { get; set; }
Property Value
Type Description
int?

An integer value representing the number of decimal places. Use null to display the default number of decimal places. The default value is null.
Remarks

This property controls the precision of decimal values displayed in the SfNumericTextBox<TValue>. When set to a specific value, the component will format numbers to show exactly that many decimal places. If set to null, the component will use the default decimal precision based on the data type and format string.

Examples
<SfNumericTextBox TValue="decimal?" Decimals="3" Placeholder="Enter value">
</SfNumericTextBox>

FloatLabelType

Gets or sets the floating label behavior of the SfNumericTextBox<TValue>. The Placeholder text act as a lable.

Declaration
[Parameter]
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 Numeric TextBox component as a label after focusing it. If the FloatLabelType is Always, the placeholder text is displayed as a label above the Numeric TextBox component.

Examples

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

<SfNumericTextBox TValue="int?" Placeholder="Enter the value" FloatLabelType="FloatLabelType.Auto">
</SfNumericTextBox>

Format

Gets or sets the format string used to display numeric values.

Declaration
[Parameter]
public string Format { get; set; }
Property Value
Type Description
string

A string value representing the format pattern. The default value is n2 which represents a number with two decimal places.
Remarks

You can customize the format string according to your requirements. The format string follows the standard format specifiers used in .NET formatting. For example, n3 would display a number with three decimal places.

Examples
<SfNumericTextBox TValue="decimal?" Placeholder="Enter the value" Format="n3" >
</SfNumericTextBox>

HtmlAttributes

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

Declaration
[Parameter]
public Dictionary<string, object> HtmlAttributes { get; set; }
Property Value
Type Description
Dictionary<string, 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
<SfNumericTextBox TValue="int?" HtmlAttributes="@CustomAttribute">
</SfNumericTextBox>
@code{
    Dictionary<string, object> CustomAttribute = new Dictionary<string, object>()
    {
        { "title", "Please enter the unit" }
    };
}

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
[Parameter(CaptureUnmatchedValues = true)]
public Dictionary<string, object> InputAttributes { get; set; }
Property Value
Type Description
Dictionary<string, 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
<SfNumericTextBox TValue="int?" Placeholder="Enter the PIN" @attributes="@CustomAttribute">
</SfNumericTextBox>
@code{
    Dictionary<string, object> CustomAttribute = new Dictionary<string, object>()
    {
        { "maxlength", "4" }
    };
}

Max

Gets or sets the maximum allowable value for the input.

Declaration
[Parameter]
public TValue Max { get; set; }
Property Value
Type Description
TValue

The maximum allowable value for the input. The default value is determined by the maximum possible value for the data type.
Remarks

This property defines the upper boundary for values that can be entered in the SfNumericTextBox<TValue>. When StrictMode is enabled, values exceeding this maximum will be automatically corrected to this maximum value. When StrictMode is disabled, values can exceed this maximum but will be flagged with an error state. The spin buttons and keyboard interactions respect this maximum limit.

Examples
<SfNumericTextBox TValue="int?" Placeholder="Enter the value" Max="10">
</SfNumericTextBox>

Min

Gets or sets the minimum allowable value for the input.

Declaration
[Parameter]
public TValue Min { get; set; }
Property Value
Type Description
TValue

The minimum allowable value for the input. The default value is determined by the minimum possible value for the data type.
Remarks

This property defines the lower boundary for values that can be entered in the SfNumericTextBox<TValue>. When StrictMode is enabled, values below this minimum will be automatically corrected to this minimum value. When StrictMode is disabled, values can go below this minimum but will be flagged with an error state. The spin buttons and keyboard interactions respect this minimum limit.

Examples
<SfNumericTextBox TValue="int?" Placeholder="Enter the value" Min="5">
</SfNumericTextBox>

Placeholder

Gets or sets the text that is displayed when the SfNumericTextBox<TValue> has no value and remove on the focus.

Declaration
[Parameter]
public string Placeholder { get; set; }
Property Value
Type Description
string

The text that is displayed when the TextBox has no value. The default value is String.Empty.
Remarks

The property depends on the FloatLabelType property, The placeholder text acts as a label.

Readonly

Gets or sets the boolean value whether the SfNumericTextBox<TValue> allows the user to change the text.

Declaration
[Parameter]
public bool Readonly { get; set; }
Property Value
Type Description
bool

true, if the TextBox component cannot be edited. Otherwise, false.

ShowClearButton

Get or sets a value that indicates whether the clear button is displayed in SfNumericTextBox<TValue> component.

Declaration
[Parameter]
public bool ShowClearButton { get; set; }
Property Value
Type Description
bool

true, if the clear button should be shown. Otherwise, false.The default is false.

ShowSpinButton

Gets or sets a value indicating whether to display spin buttons for incrementing and decrementing the numeric value.

Declaration
[Parameter]
public bool ShowSpinButton { get; set; }
Property Value
Type Description
bool

true if spin buttons should be shown; otherwise, false. The default value is true.
Remarks

When enabled, the SfNumericTextBox<TValue> displays up and down arrow buttons that allow users to increment or decrement the numeric value. The spin buttons provide an intuitive way for users to adjust values without typing, especially useful for precise value adjustments. The increment/decrement amount is controlled by the Step property.

Examples
<SfNumericTextBox TValue="int?" ShowSpinButton="true" Step="5">
</SfNumericTextBox>

Step

Gets or sets the increment or decrement value for changing the numeric value.

Declaration
[Parameter]
public TValue Step { get; set; }
Property Value
Type Description
TValue

The step value that determines how much the numeric value changes when interacting with the component. The default value varies based on the data type.
Remarks

This property defines the amount by which the value increases or decreases when users interact with the spin buttons, use keyboard arrow keys, or scroll the mouse wheel. The step value should be appropriate for the expected range and precision of values in your application. For example, use smaller step values for decimal numbers requiring precision, and larger step values for whole numbers.

Examples
<SfNumericTextBox TValue="int?" Placeholder="Enter the value" Step="5">
</SfNumericTextBox>

StrictMode

Gets or sets a value indicating whether the component operates in strict mode for value validation.

Declaration
[Parameter]
public bool StrictMode { get; set; }
Property Value
Type Description
bool

true if input values are restricted between the minimum and maximum range; otherwise, false. The default value is true.
Remarks

When StrictMode is enabled (true), the input value will be automatically constrained between the Min and Max values. If a user enters a value outside this range, it will be corrected to the nearest boundary value when the component loses focus. When disabled (false), the component allows any value, even if it falls outside the specified range. In this case, an error class is applied to highlight invalid values visually.

Examples
<SfNumericTextBox TValue="int?" Min="1" Max="100" StrictMode="true">
</SfNumericTextBox>

TabIndex

Gets or sets the tab order of the SfNumericTextBox<TValue> component.

Declaration
[Parameter]
public int TabIndex { get; set; }
Property Value
Type Description
int

An integer value representing the tab index of the component.

ValidateDecimalOnType

Gets or sets a value indicating whether to perform decimal validation during typing.

Declaration
[Parameter]
public bool ValidateDecimalOnType { get; set; }
Property Value
Type Description
bool

true if decimal validation should be performed during typing; otherwise, false. The default value is false.
Remarks

When enabled, this property validates decimal input in real-time as the user types, preventing invalid decimal characters from being entered. This provides immediate feedback and ensures that only valid decimal values can be typed into the SfNumericTextBox<TValue>. When disabled, validation occurs only when the component loses focus or when the value is programmatically set.

Examples
<SfNumericTextBox TValue="decimal?" ValidateDecimalOnType="true">
</SfNumericTextBox>

Width

Gets or sets the width of the SfNumericTextBox<TValue> component.

Declaration
[Parameter]
public string Width { get; set; }
Property Value
Type Description
string

The preferred width in pixels or percentage value. The default value is 100%.
Examples
<SfNumericTextBox TValue="int?" Width="200px">
</SfNumericTextBox>

Methods

BuildRenderTree(RenderTreeBuilder)

Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)
Parameters
Type Name Description
RenderTreeBuilder __builder
Overrides

ChangeHandler(ChangeEventArgs)

Handles the change event when the input value is modified by the user.

Declaration
protected override Task ChangeHandler(ChangeEventArgs args)
Parameters
Type Name Description
ChangeEventArgs args

The change event arguments containing the new input value.
Returns
Type Description
Task

A Task representing the asynchronous change handling operation.
Overrides
Remarks

This method is responsible for processing user input and performs the following operations:

  • Handles drag-and-drop input sanitization
  • Processes full-width character conversion
  • Validates numeric input against allowed patterns
  • Handles both double and decimal parsing based on data type
  • Applies strict mode constraints and formatting
  • Manages paste operations and invalid input states
The method supports culture-specific number formatting and ensures proper validation of numeric input.

DecrementAsync(TValue)

Decrements the value asynchronously by the specified step.

Declaration
public Task DecrementAsync(TValue step)
Parameters
Type Name Description
TValue step

The step value by which to decrement the current value. If not provided, the numeric value will be decremented based on the Step property value.
Returns
Type Description
Task

A Task representing the asynchronous operation.
Remarks

This method decreases the current value of the SfNumericTextBox<TValue> by the specified step amount. The operation is performed asynchronously and will trigger the change event after the value is updated. If the resulting value goes below the minimum allowed value, it will be constrained to the minimum value.

Examples
// Decrement by a custom step value
await numericTextBox.DecrementAsync(5);

// Decrement by the default step value
await numericTextBox.DecrementAsync(default(TValue));

FocusAsync()

Sets the focus to the NumericTextBox component for interaction.

Declaration
public Task FocusAsync()
Returns
Type Description
Task

A Task representing the asynchronous operation.
Remarks

This method programmatically focuses the SfNumericTextBox<TValue> component, making it ready for user input. When focused, the component will be highlighted and ready to receive keyboard input or other user interactions. This is useful for accessibility scenarios or when you need to direct user attention to the component.

Examples
// Focus the numeric textbox
await numericTextBox.FocusAsync();

FocusHandler(FocusEventArgs)

Handles the focus event when the numeric textbox receives focus.

Declaration
protected override Task FocusHandler(FocusEventArgs args)
Parameters
Type Name Description
FocusEventArgs args

The focus event arguments containing event details.
Returns
Type Description
Task

A Task representing the asynchronous focus handling operation.
Overrides
Remarks

This method is called when the input element receives focus. It triggers client-side focus handling only if the component is enabled, not readonly, and the focus handler hasn't been triggered yet. The focus handler manages input formatting and user interaction states.

FocusOutAsync()

Removes the focus from the NumericTextBox component, if the component is in focus state.

Declaration
public Task FocusOutAsync()
Returns
Type Description
Task

A Task representing the asynchronous operation.
Remarks

This method programmatically removes focus from the SfNumericTextBox<TValue> component. If the component is currently focused, it will lose focus and any pending input will be processed. This method is useful for form validation scenarios or when you need to blur the component programmatically.

Examples
// Remove focus from the numeric textbox
await numericTextBox.FocusOutAsync();

FocusOutHandler(FocusEventArgs)

Handles the blur event when the numeric textbox loses focus.

Declaration
protected override Task FocusOutHandler(FocusEventArgs args)
Parameters
Type Name Description
FocusEventArgs args

The focus event arguments containing event details.
Returns
Type Description
Task

A Task representing the asynchronous blur handling operation.
Overrides
Remarks

This method is called when the input element loses focus and performs the following operations:

  • Triggers the Blur event if subscribed
  • Validates and formats the current input value
  • Handles device-specific behavior for mobile platforms
  • Updates float label sizing
  • Parses and converts input text to appropriate numeric types
The method prevents recursive calls and ensures proper value conversion based on the data type (double or decimal).

FormatValue(string)

Converts a string input value to the appropriate numeric type based on the current component configuration.

Declaration
protected override TValue FormatValue(string genericValue)
Parameters
Type Name Description
string genericValue

The string value to be converted to the numeric type.
Returns
Type Description
TValue

The converted numeric value of type TValue, or default value if conversion fails.
Overrides
Remarks

This method handles culture-specific number parsing, decimal separator validation, and supports both double and decimal numeric types. It also manages formatting for focused input states and validates number formats.

Exceptions
Type Condition
Exception

Logs any unexpected errors that occur during value conversion to the console.

FormatValueAsString(TValue)

Formats the specified numeric value as a string representation based on the current formatting settings.

Declaration
protected override string FormatValueAsString(TValue formatValue)
Parameters
Type Name Description
TValue formatValue

The numeric value to be formatted.
Returns
Type Description
string

A string representation of the formatted value, or null if an error occurs.
Overrides
Remarks

This method applies culture-specific formatting, handles exponential notation, manages decimal separators, and updates ARIA attributes for accessibility. The formatting behavior differs based on whether the input is focused or not.

Exceptions
Type Condition
Exception

Logs any unexpected errors that occur during formatting to the console.

GetFormattedText()

Gets the formatted text representation of the current value.

Declaration
public string GetFormattedText()
Returns
Type Description
string

A string containing the formatted text representation of the current value.
Remarks

This method returns the current value of the SfNumericTextBox<TValue> formatted according to the component's formatting settings. The formatting includes decimal places, currency symbols, percentage signs, and other culture-specific formatting as configured. This is useful when you need to display the formatted value in other parts of your application.

Examples
// Get the formatted text of the current value
string formattedText = numericTextBox.GetFormattedText();

GetPersistDataAsync()

Gets the properties to be maintained in the persisted state.

Declaration
public Task<string> GetPersistDataAsync()
Returns
Type Description
Task<string>

A Task<TResult> representing the asynchronous operation. The task result contains a string with the persisted data.
Remarks

This method retrieves the persisted state data for the SfNumericTextBox<TValue> component from the browser's local storage. The persisted data includes component properties that should be maintained across page refreshes or application restarts. This is useful for maintaining user preferences and component state in web applications.

Examples
// Get persisted data
string persistedData = await numericTextBox.GetPersistDataAsync();

IncrementAsync(TValue)

Increments the NumericTextBox value with the specified step value.

Declaration
public Task IncrementAsync(TValue step)
Parameters
Type Name Description
TValue step

Specifies the value used to increment the NumericTextBox value. If not provided, the numeric value will be incremented based on the Step property value.
Returns
Type Description
Task

A Task representing the asynchronous operation.
Remarks

This method increases the current value of the SfNumericTextBox<TValue> by the specified step amount. The operation is performed asynchronously and will trigger the change event after the value is updated. If the resulting value exceeds the maximum allowed value, it will be constrained to the maximum value.

Examples
// Increment by a custom step value
await numericTextBox.IncrementAsync(10);

// Increment by the default step value
await numericTextBox.IncrementAsync(default(TValue));

Implements