NumericTextBox Overview

The Kendo UI NumericTextBox widget converts an <input> element into a numeric, percentage, or currency textbox.

The specific format defines the conversion data type. The widget renders Spin buttons which increase or decrease the value with a predefined step. The NumericTextBox accepts only numeric entries. The widget uses kendo.culture.current culture to determine the number precision and other culture-specific properties.

Getting Started

Initialize the NumericTextBox

To initialize the NumericTextBox, use the following example.

<input id="textBox" />

<script>
    $(document).ready(function(){
        $("#textBox").kendoNumericTextBox();
    });
</script>

When initialized, the NumericTextBox wraps the <input> element with a <span> tag and renders Spin buttons.

Important

When you get a reference to the NumericTextBox, always use id instead of a class selector. Behind the scenes, the NumericTextBox creates a secondary element that represents the visual look of the widget and copies over all non-id attributes including the class. When you use the class for referencing the widget, this behavior causes unexpected results.

Configuration

The NumericTextBox provides configuration options that can be set during initialization. The available properties are:

• Value of the widget
• Minimum and/or maximum values
• Increment step
• Precision of numbers
• Rounding of numbers
• Number format (any valid number format is allowed)

For more information on its methods and configuration options, review the API Reference of the NumericTextBox.

Defaults

The following example demonstrates how to customize the default settings of the NumericTextBox.

Example

 <input id="textbox">

 <script>
    $("#textbox").kendoNumericTextBox({
        value: 10,
        min: -10,
        max: 100,
        step: 0.75,
        format: "n",
        decimals: 3
    });
</script>

Currency NumericTextBox

The following example demonstrates how to create a currency NumericTextBox.

Example

 <input id="textbox">

 <script>
    $("#textbox").kendoNumericTextBox({
        format: "c2" //Define currency type and 2 digits precision
    });
</script>

Percentage NumericTextBox

The following example demonstrates how to create a percentage NumericTextBox.

Example

<input id="textbox">

 <script>
    $("#textbox").kendoNumericTextBox({
        format: "p",
        value: 0.15 // 15 %
    });
</script>

Precision of Numbers

The widget controls the precision of the entered number by using the value of the decimals option. The number is limited to the decimals length.

By default, the widget does not restrict the length of the typed value. To enforce a specific fraction length during editing, set the restrictDecimals option to true.

Rounding of Numbers

The widget controls the precision of the entered number using the half-up rounding technique. To disable this functionality, use the round configuration option. Once you turn off the rounding, the value is truncated up to the desired precision length without rounding it.

Range Validation

You can restrict the value of the NumericTextBox to a specific range by using either of the following approaches:

• Restrict the input value between a specific min and max range. The typed value gets modified to fit the range on blur.

• Use a custom Kendo UI Validator rule to restrict the input value. The invalid value keeps unchanged and the user is notified for the incorrect input with a friendly error message.

  For more details, refer to the article on the custom validation rules of the Validator.

  To see the suggested implementation in action, navigate to the online demo on range validation.

Support for label Element

Because of its complex rendering, you need additional implementation if you focus the widget by using a label element. For more information on how to do it, refer to this Kendo UI Dojo snippet.

Known Limitations

Value Precision

The NumericTextBox uses a JavaScript Number object to keep its value which has a certain precision limitation. In general, the Number object persists its precision up to 16 digits. Numbers longer than 16 digits get converted to exponential numbers and lose their precision. Because the widget relies on a Number object, it gets the same precision limitation.

This limitation comes from JavaScript itself and you cannot work around it in a feasible way. You are recommended to use an <input> element with server validation because some server languages can parse long numbers.

On the other hand, if the user enters a number with a greater precision than is currently configured through the decimals property, the widget value will be rounded. For more details and examples, refer to the API documentation on decimals.

Input Type

The NumericTextBox uses <input type="text" /> elements. If initialized from an <input type="number" /> element, the widget switches the input type to text. This behavior is enables the support of the comma (,) as a decimal separator in some non-"en-US" cultures. Currently, browsers ignore the culture of the client and the values that contain a comma as a decimal separator.

The side effect of using a text input type is that it prevents the numeric keyboard from appearing on mobile devices with context-specific software keyboards.

To render a numeric software keyboard, use either of the following workarounds:

• Use a plain numeric input for mobile devices and add a k-textbox CSS class to apply Kendo UI styling.
• Change the input type back to number after the NumericTextBox initializes. This is possible only for cultures that use a dot (.) as a decimal separator.

Example

    /* widget is initialized */
    $("#my-numeric-textbox").kendoNumericTextBox({ /*...*/ });

    /* set the input type to "number" */
    $("#my-numeric-textbox").attr("type", "number");

    /* or if the widget object is already available */
    var numericTextBoxObject = $("#my-numeric-textbox").data("kendoNumericTextBox");
    numericTextBoxObject.element.attr("type", "number");

See Also

Other articles and how-to examples on the Kendo UI NumericTextBox:

• How to Add Title Attribute
• How to Change Text Color
• How to Focus Widget on Label Click
• How to Persist Old Value
• How to Select All Text on Focus
• How to Update Value on Keyup
• How to Update Value on Spin
• How to Use Custom Culture Script
• Overview of the ASP.NET MVC HtmlHelper Extension for the NumericTextBox Widget
• Overview of the NumericTextBox JSP Tag
• Overview of the NumericTextBox PHP Class
• NumericTextBox JavaScript API Reference