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.
Implements
Inherited Members
Namespace: Syncfusion.Blazor.Toolkit.Inputs
Assembly: Syncfusion.Blazor.Toolkit.dll
Syntax
public class SfNumericTextBox<TValue> : SfInputBase<TValue>, IAsyncDisposableType 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
AllowMouseWheel
Gets or sets a value indicating whether the mouse wheel interaction is enabled for incrementing or decrementing the value in the SfNumericTextBox<TValue> component.
Declaration
public bool AllowMouseWheel { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
- When
AllowMouseWheelis set totrue, scrolling the mouse wheel will increment or decrement the value in the SfNumericTextBox<TValue> based on the step value. - When
AllowMouseWheelis set tofalse, mouse wheel scrolling will be ignored.
Examples
<SfNumericTextBox TValue="int?" Value="10" AllowMouseWheel="false" />Created
Gets or sets an event callback that is invoked when the SfNumericTextBox<TValue> component is created and fully initialized.
Declaration
public EventCallback<object> Created { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback that receives an System.Object parameter when the component creation is complete. |
Remarks
The Created event is triggered after the NumericTextBox component has been fully rendered and initialized on the client-side. This event is useful for performing initialization tasks, setting up additional configurations, or integrating with third-party libraries that require the component to be fully rendered.
Examples
Example of handling the Created event:
<SfNumericTextBox TValue="decimal?" Created="@OnCreated">
</SfNumericTextBox>
@code {
private void OnCreated(object args)
{
// Component is fully created and rendered
Console.WriteLine("NumericTextBox component has been created successfully");
}
}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
public string Currency { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A string value representing the ISO 4217 currency code. The default value is |
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
public Nullable<int> Decimals { get; set; }Property Value
| Type | Description |
|---|---|
| System.Nullable<System.Int32> | An integer value representing the number of decimal places. Use |
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>Destroyed
Gets or sets an event callback that is invoked when the SfNumericTextBox<TValue> component is destroyed or disposed.
Declaration
public EventCallback<object> Destroyed { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback that receives an System.Object parameter when the component destruction occurs. |
Remarks
The Destroyed event is triggered when the NumericTextBox component is being removed from the DOM or disposed of. This event is useful for performing cleanup tasks, removing event listeners, or disposing of resources that were allocated during the component's lifecycle.
Examples
Example of handling the Destroyed event:
<SfNumericTextBox TValue="double?" Destroyed="@OnDestroyed" >
</SfNumericTextBox>
@code {
private void OnDestroyed(object args)
{
// Perform cleanup when component is destroyed
Console.WriteLine("NumericTextBox component has been destroyed");
}
}FloatLabelType
Gets or sets the floating label behavior of the SfNumericTextBox<TValue>. The Placeholder text acts as a label.
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 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 floating label to 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
public string Format { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A string value representing the format pattern. The default value is |
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
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 |
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
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 |
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
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
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>OnBlur
Gets or sets an event callback that is invoked when the SfNumericTextBox<TValue> component loses focus.
Declaration
public EventCallback<NumericBlurEventArgs<TValue>> OnBlur { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<NumericBlurEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback that receives a NumericBlurEventArgs<T> containing information about the blur event. |
Remarks
The Blur event is triggered when the NumericTextBox loses focus, typically when the user clicks outside the component or navigates to another control using the Tab key. You can use this event to perform validation, save data, or update the UI based on the component losing focus.
Examples
Example of handling the Blur event:
<SfNumericTextBox TValue="int?" OnBlur="@OnBlur">
</SfNumericTextBox>
@code {
private void OnBlur(NumericBlurEventArgs<int?> args)
{
// Perform validation or other actions when component loses focus
Console.WriteLine($"NumericTextBox lost focus. Current value: {args.Value}");
}
}OnFocus
Gets or sets an event callback that is invoked when the SfNumericTextBox<TValue> component receives focus.
Declaration
public EventCallback<NumericFocusEventArgs<TValue>> OnFocus { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<NumericFocusEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback that receives a NumericFocusEventArgs<T> containing information about the focus event. |
Remarks
The Focus event is triggered when the NumericTextBox receives focus, typically when the user clicks on the component or navigates to it using the Tab key. You can use this event to highlight the component, show additional UI elements, or perform initialization tasks that should occur when the component becomes active.
Examples
Example of handling the Focus event:
<SfNumericTextBox TValue="float?" OnFocus="@OnFocus">
</SfNumericTextBox>
@code {
private void OnFocus(NumericFocusEventArgs<float?> args)
{
// Handle focus event
Console.WriteLine($"NumericTextBox received focus. Current value: {args.Value}");
}
}OnInput
Gets or sets an event callback that is invoked when the user types or modifies the value in the SfNumericTextBox<TValue> component.
Declaration
public EventCallback<ChangeEventArgs> OnInput { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<Microsoft.AspNetCore.Components.ChangeEventArgs> | An Microsoft.AspNetCore.Components.EventCallback that receives a Microsoft.AspNetCore.Components.ChangeEventArgs containing the previous and current values during real-time input. |
Remarks
The OnInput event is triggered whenever the user modifies the numeric value in the TextBox, either by typing, using the spin buttons, or through programmatic changes. This event provides both the previous and current values, allowing you to track changes and implement custom logic based on value modifications.
Examples
Example of handling the OnInput event:
<SfNumericTextBox TValue="int?" Placeholder="Enter the value" OnInput="@OnInput">
</SfNumericTextBox>
@code {
private void OnInput(ChangeEventArgs args)
{
Console.WriteLine("Input value changed");
}
}Placeholder
Gets or sets the placeholder text that is displayed when the SfNumericTextBox<TValue> is empty and is removed when focused.
Declaration
public string Placeholder { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | The text that is displayed when the TextBox has no value. The default value is |
Remarks
The property depends on the FloatLabelType property. The placeholder text acts as a label.
Readonly
Gets or sets a value indicating whether the SfNumericTextBox<TValue> allows users to change the text.
Declaration
public bool Readonly { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
ShowClearButton
Gets or sets a value that indicates whether the clear button is displayed in the SfNumericTextBox<TValue> component.
Declaration
public bool ShowClearButton { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
ShowSpinButton
Gets or sets a value indicating whether to display spin buttons for incrementing and decrementing the numeric value.
Declaration
public bool ShowSpinButton { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
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
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
public bool StrictMode { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
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
public int TabIndex { get; set; }Property Value
| Type | Description |
|---|---|
| System.Int32 | 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
public bool ValidateDecimalOnType { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
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>ValueChange
Gets or sets an event callback that is invoked when the value of the SfNumericTextBox<TValue> component changes.
Declaration
public EventCallback<ChangeEventArgs<TValue>> ValueChange { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<ChangeEventArgs<TValue>> | An Microsoft.AspNetCore.Components.EventCallback that receives a ChangeEventArgs<T> containing the previous and current values when the component's value changes. |
Remarks
The ValueChange event is triggered whenever the user modifies the numeric value in the TextBox, either by typing, using the spin buttons, or through programmatic changes. This event provides both the previous and current values, allowing you to track changes and implement custom logic based on value modifications.
Examples
Example of handling the ValueChange event:
<SfNumericTextBox TValue="int?" Placeholder="Enter the value" ValueChange="@OnValueChange">
</SfNumericTextBox>
@code {
private void OnValueChange(ChangeEventArgs<int?> args)
{
var previousValue = args.PreviousValue;
var currentValue = args.Value;
Console.WriteLine($"Value changed from {previousValue} to {currentValue}");
}
}Width
Gets or sets the width of the SfNumericTextBox<TValue> component.
Declaration
public string Width { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | The preferred width in pixels or percentage value. The default value is |
Examples
<SfNumericTextBox TValue="int?" Width="200px">
</SfNumericTextBox>Methods
BuildRenderTree(RenderTreeBuilder)
Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder | __builder |
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 |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.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 focus to the SfNumericTextBox<TValue> component for user interaction.
Declaration
public Task FocusAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.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();FocusOutAsync()
Removes the focus from the NumericTextBox component, if the component is in focus state.
Declaration
public Task FocusOutAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.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();GetFormattedText()
Gets the formatted text representation of the current value.
Declaration
public string GetFormattedText()Returns
| Type | Description |
|---|---|
| System.String | A System.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 |
|---|---|
| System.Threading.Tasks.Task<System.String> | A System.Threading.Tasks.Task<> representing the asynchronous operation. The task result contains a System.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 |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.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));