Editor Widgets

This article describes common principles of working with widgets intended to specify Boolean, numeric, string values, etc.

Common Tasks

When working with an editor widget, you can often encounter tasks common for all editor widgets. This section describes the most important common tasks, such as getting and setting the widget value and handling the value change event.

Get And Set a Widget Value

The value of an editor widget is held in the value configuration option. You can use any of the following approaches to get and modify widget value.

Set Value

To specify the initial value for the widget, assign it to the value option within the widget constructor.

JavaScript
var widgetOptions = { 
    value: "My Text"
};

Get Value

To get the option value at runtime, get the widget instance and call its option(optionName) method passing "value" as a parameter.

JavaScript
// Get the widget instance
...
var textBoxValue = textBoxInstance.option("value");

In MVVM approach, to get an option value, get the value of the corresponding view or application model field.

Angular Approach
JavaScript
var text = $scope.value;
Knockout Approach
JavaScript
var text = viewModel.value;

Modify Value

To modify the option value at runtime, call the option(optionName, optionValue) method of the widget instance. The optionValue parameter should take on the "value" string, while the optionValue parameter ought to take on the required value.

JavaScript
var textBox = $("#textBoxContainer").dxTextBox("instance");
var textBoxValue = textBox.option("value", "New Text");

In MVVM, to set widget value, assign a new value to the corresponding view or application model field.

Angular Approach
JavaScript
$scope.textBoxValue = "New Text";
Knockout Approach
JavaScript
textBoxValue("New Text");

In MVVM approach, to get and set the widget value at runtime, provide a two-way binding between the value option and the corresponding field of a view or application model.

Angular Approach
JavaScript
function Controller($scope) {
    $scope.textBoxValue = "My Text";
}
HTML
<div ng-controller="Controller">
    <div dx-text-box="{ bindingOptions: { value: 'textBoxValue' }}"></div>
</div>
NOTE
If you need to get and set the widget value at runtime, you can also bind an appropriate $scope object field with the widget element using the ng-model directive.
HTML
<div ng-controller="Controller">
    <div ng-model="textBoxValue" dx-text-box="{ }"></div>
</div>
Knockout Approach
JavaScript
var textBoxValue = ko.observable("My Text");
HTML
<div data-bind="dxTextBox: { value: textBoxText }"></div>

Handle The Value Change Event

To timely process a new widget value, the editor widgets require you to handle the value change event...

Pass the event handling function to the onValueChanged option when creating the widget.

JavaScript
var valueChangeHandler = function(e){
    alert("New value: " + e.value + ", old value: " + e.previousValue);
}
var textBoxOptions = {
    onValueChanged: valueChangeHandler
}

...or at runtime.

JavaScript
// Get the widget instance
...
textBoxInstance.option("onValueChange", valueChangeHandler);

Note that the handling function includes the e parameter that takes on an object containing the widget value.

In the Angular Approach, you may use the $watch listener for the $scope object property bound to the value option.

JavaScript
function Controller($scope) {
    $scope.text = "";
    $scope.$watch("text", function(newValue, oldValue) {
        alert("The text box value has been changed from " + oldValue + " to " + newValue);
    });
}
HTML
<div ng-controller="Controller">
    <div dx-text-box="{ bindingOptions: { 'value': 'text' }}"></div>
</div>

In the Knockout approach, you may subscribe the change event of the observable variable passed to the value option of the widget.

JavaScript
var text = ko.observable("");
text.subscribe(function(value){
    alert("The text box value has been changed to " + value);
});
HTML
<div data-bind="dxTextBox: { value: text }"></div>

Text Editors

The following editor widgets also support the text editor functionality. Text editors are intended to display a string, a numeric or date/time value and allow a user to edit this value.

These widgets are based on the input HTML element. In addition to editor specific options, they include options that enable you to specify handlers for events of the underlying input element (onEnterKey, onFocusIn, onFocusOut, etc.).

JavaScript
var textBoxOptions = {
    onFocusIn: function() {
        alert("The widget has got focus");
    }
}

Text editor widgets support the read-only state, which can be enabled or disabled using the readOnly configuration option. You can also specify the widget placeholder text using the placeholder option. In addition, text editor widgets can show the Clear button that clears the widget value. Use the showClearButton option to specify button visibility.

List of Editor Widgets

The following DevExtreme UI widgets are related to the editors category.

dxAutocomplete

The dxAutocomplete widget is a text editor that suggests ways of completing the text being typed.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

As the widget displays a collection of items, it supports common Collection Container widget functionality and enables you to carry out the following tasks.

In addition to common editor and collection container functionality, the widget enables you to perform the following adjustments.

Specify Search parameters

The widget only displays items that satisfy the specified criterion. The widget can use the contains or startswith binary operation to filter data items. Assign the required operation name to the searchMode option to specify the search criterion. The default search mode is contains.

By default, the dxAutocomplete widget displays a list of available completions when an end-user types in at least one character. Use the minSearchLength option to change this behavior. This option specifies the minimum number of characters that must be entered into the search box to begin a search.

You can also specify the time period in milliseconds before a search is executed using the searchTimeout option.

JavaScript
var autocompleteOptions = {
    dataSource: autocompleteData,
    searchMode: 'startswith',
    minSearchLength: 3,
    searchTimeout: 500
}

Tweak For an Item Structure

If a data source item is a string value, the widget compares the entered text with this value to filter data items. If an item is an object, you should specify which property will be used for comparison. Assign the required property name to the valueExpr option.

JavaScript
var autocompleteData = [
    { "name": "Alabama", "capital": "Montgomery" },
    { "name": "Alaska", "capital": "Juneau" },
    { "name": "Arizona", "capital": "Phoenix" }
    . . .
]
var autocompleteOptions = {
    dataSource: autocompleteData,
    valueExpr: 'name'
}

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Alt + Down arrow
    Open the popup window.

  • Alt + Up arrow
    Close the popup window.

  • Esc
    Close the popup window and remove focus from the widget.

  • Up/down arrow (page up/down) Move to the previous/next item.

  • Enter (Space) Apply the current item.

dxCalendar

The dxCalendar widget displays a calendar and enables a user to select the required date within the specified date range. You can access the selected date using the value option.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Specify the date range

The date range is specified by the min and max options, which take on a Date object representing the earliest and latest date respectively.

JavaScript
var calendarOptions = {
    min: new Date(2000,1,1),
    max: new Date(2020,12,31)
}

Specify the zoom level

The size of a date range displayed on a single calendar page is specified using the zoomLevel option, which accepts the "month", "year", "decade" and "century" values. When a user clicks the calendar header, the zoom level is decreased, when a user clicks a calendar item, the zoom level is increased. The maxZoomLevel and minZoomLevel options specify maximum and minimum zoom levels a user can specify.

JavaScript
var calendarOptions = {
    minZoomLevel: 'century',
    maxZoomLevel: 'month',
    zoomLevel: 'year'
}

Specify which day of the week is displayed first

The widget enables you to specify which day of the week is to be displayed in the first column. Pass the 0 based index of the required day to the firstDayOfWeek option.

  • 0 - Sunday
  • 1 - Monday
  • 2 - Tuesday
  • 3 - Wednesday
  • 4 - Thursday
  • 5 - Friday
  • 6 - Saturday
JavaScript
var calendarOptions = {
    firstDayOfWeek: 1
}

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Left/right arrow
    Highlights the previous/next day.

  • Up/down arrow
    Highlights a day a week before/after the currently highlighted day.

  • Ctrl + left/right arrow (page up/down)
    Displays the previous/next month.

  • Enter Selects the highlighted day.

dxCheckBox

The dxCheckBox widget allows a user to check or uncheck an option, and perform a specified action when widget value changes.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Specify the widget state

The widget takes on the "checked", "unchecked" or "indeterminate" state if the value option is set to true, false or undefined respectively.

JavaScript
var checkBoxOptions = {
    value: undefined
}

Specify the widget text

You can specify the check box caption using the text option.

JavaScript
var checkBoxOptions = {
    text: "Check me"
}

Keyboard support

An end-user can change the widget value using the Enter or Space key.

dxColorBox

The dxColorBox widget allows a user to specify a color value manually or pick it out from the drop-down editor.

In addition to common Editor functionality, the dxColorBox widget supports options common for Overlay widgets, which affect popup window behavior.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Access the selected color

You can get or set the selected color using the value option. You can use any CSS compatible color format ("#FF0000", "Red", "rgb(255, 0, 0)") to specify the current color. If a user selects a color using the popup window, the selected color is displayed in the hexadecimal format ("#FF0000").

JavaScript
var colorBoxOptions = {
    value: "#FF9000"
}

Enable alpha channel support

By default, the widget enables an end-user to select non-transparent colors. Set the editAlphaChannel option to true to enable an end-user to specify a color containing the alpha channel component.

JavaScript
var colorBoxOptions = {
    value: "rgba(255, 144, 0, 0.3)",
    editAlphaChannel: true
}

If this option is set to true, the widget displays the selected color in the "rgba(255, 144, 0, 0.3)" format.

Specify button text

The widget enables you to specify a custom text for the OK and Cancel buttons displayed at the bottom of the popup window using the applyButtonText and cancelButtonText options respectively.

JavaScript
var colorBoxOptions = {
    applyButtonText: "Apply color",
    cancelButtonText: "Close window"
}

The string representation of the selected color can be accessed using the value option.

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Up/down/left/right arrow
    Move the central color handler.

  • Ctrl + up/down arrow
    Move RGB handler at up/down.

  • Ctrl + left/right arrow
    Move alpha channel handler left/right.

  • Enter Select the highlighted day.

dxDateBox

The dxDateBox widget displays the date and time value in a specified format, and enables a user to pick the required date/time value within the specified range.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Specify the date range

The date time range is specified by the min and max options, which take on a Date object representing the earliest and latest date and time respectively.

JavaScript
var dateBoxOptions = {
    min: new Date(2000,1,1),
    max: new Date(2020,12,31)
}

Specify the format of the data displayed by the widget

Besides the date information displayed by default, the dxDateBox widget can display time information, and the date and time simultaneously depending on the format option, which can take on one of the following values.

  • date
    The widget displays only the date.

  • time
    The widget displays only the time.

  • datetime
    The widget displays both the date and the time.

JavaScript
var dateBoxOptions = {
    format: "datetime"
}

Specify the date/time picker type

The widget enables an end-user to pick date/time using a drop-down calendar, rollers or a value list depending on the pickerType option. In addition to the desired picker type, the option accepts the "native" value, which makes the date box use the picker native for the current platform.

Specify the value format string

The formatString option specifies the Globalize date format used to display data picked from the calendar.

JavaScript
var dateBoxOptions = {
    formatString: "D"
}

Adjust widget behavior

You can specify whether the widget value is applied instantly or when a user clicks the apply button using the applyValueMode option.

JavaScript
var dateBoxOptions = {
    pickerType: calendar,
    applyValueMode: "instantly"
}

Keyboard support

An end-user can use the following keys to interact with the widget, which are available when a popup window is displayed.

  • Tab/Shift+Tab
    Moves focus to the next/previous date or time part.

  • Up/down arrow
    Changes the focused value by 1 step.

  • Page up/down
    Changes the focused value by 5 steps.

  • Enter (Space)
    Applies the current values and closes the popup window.

dxFileUploader

The dxFileUploader widget enables you to specify a file or several files to be uploaded to the server. The widget is based on an input element with the type attribute set to "file". Refer to the dxFileUploader guide for more information.

dxLookup

The dxLookup widget allows an end-user to select predefined values from a lookup window. Refer to the dxLookup guide for more information.

View Demo

dxNumberBox

The dxNumberBox widget allows a user to enter a number within the specified range.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Specify the range of available values

Specify the range of available values using the min and max options.

JavaScript
var numberBoxOptions = {
    min: 0,
    max: 100
}

Enable/disable spin buttons

To enable an end-user's ability to increase or decrease widget value using spin buttons, assign true to the showSpinButtons option. The step option specifies a number added to or subtracted from the widget value on a single spin button click.

JavaScript
var numberBoxOptions = {
    showSpinButtons: true,
    step: 10
}

If the widget is displayed on a touch device, it uses touch-friendly spin buttons regardless of the current theme.

Keyboard support

An end-user can use the Up/Down arrow key or mouse wheel to increase/decrease widget value by a step.

dxProgressBar

The dxProgressBar widget displays the current progress within the specified range.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Specify the required range

The range boundaries are specified by the min and max options.

JavaScript
var progressBarOptions = {
    min: 0,
    max: 100
}

Show/hide progress status

The widget displays the current progress status if the showStatus option is set to true. The status format is specified using the statusFormat option, which takes on a string holding a Globalize format pattern, or a function that returns a status string. The function should take on the following arguments.

  • ratio
    Specifies the ratio of the current progress to the entire range. (From 0 to 1)

  • value
    The current widget value, which can also be accessed using the value option.

JavaScript
var progressBarOptions = {
    min: 0,
    max: 1000,
    showStatus: true,
    statusFormat: function(ratio, value) {
        return ratio * 100 + "% (" + value + ")";
    }
}

If the widget has the same options as illustrated in the example above, it will show the "35% (350)" status if the current value is 350.

dxRadioGroup

The dxRadioGroup widget contains a set of radio buttons and enables an end-user to select one of them.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

As the widget displays a collection of items, it supports common Collection Container widget functionality and enables you to carry out the following tasks.

In addition to common editor and collection container functionality, the widget enables you to perform the following adjustments.

Specify an item text

The widget creates a radio button for each item of the data source specified using the dataSource option. An item object should contain the text property that specifies the text displayed by the corresponding radio button.

JavaScript
var colors = [
    { text: "red", value: "#FF0000" },
    { text: "green", value: "#00FF00" },
    { text: "blue", value: "#0000FF" }
]
var radioGroupOptions = {
    dataSource: colors
}

Access the selected item

You can access the selected value using the value option. The valueExpr option specifies the item object property whose value is accessed using the value option. You can pass "this" to the valueExpr option to access the entire item object.

var radioGroupOptions = {
    dataSource: colors,
    valueExpr: 'value'
}

Specify the widget layout

The layout option enables you to specify whether the widget arranges radio buttons vertically or horizontally.

var radioGroupOptions = {
    dataSource: colors,
    layout: 'horizontal'
}

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Up/down arrow (page up/down)
    Move focus to the previous/next item.

  • Home/End
    Move focus to the first/last element.

  • Enter (Space)
    Select the focused element.

dxRangeSlider

The dxRangeSlider widget allows a user to specify a range of numeric values.

View Demo

Although the dxRangeSlider widget is an editor widget, common Editor widget tasks described at the beginning of this article are carried out slightly differently for this widget.

Get and Set the widget value

As the widget is intended to specify a range, it does not contain the value option, but it contains the start and end options, which are used to specify the selected range.

JavaScript
var rangeSliderOptions = {
    start: 30,
    end: 70
}

Handle the value change event

The event handling function of the value changed event has other fields in the function parameter.

JavaScript
var valueChangeHandler = function(e){
    alert("The selected range is from " + e.start + " to " + e.end);
}
var rangeSliderOptions = {
    onValueChanged: valueChangeHandler
};

As for the rest, the value event handling follows the same principles described in the Handle the Value Change Event](/Documentation/Guide/UIWidgets/UIWidgetCategories/EditorWidgets/?version=151#UIWidgetsUIWidgetCategoriesEditorWidgetsCommonTasksHandleTheValueChangeEvent) topic.

Specify the range of available values

The boundaries of the available value range are specified by the min and max options.

JavaScript
var rangeSliderOptions = {
    min: 0,
    max: 100
}

Specify the slider step

The step option specifies the difference between neighboring widget values.

JavaScript
var sliderOptions = {
    step: 10
}

Show/hide labels

The dxRangeSlider widget can display labels for the boundary values. The label options are specified using the label option, which takes an object containing the following properties.

  • format
    Specifies a format for labels. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether labels are located over or under the scale respectively.

  • visible
    Specifies whether or not range slider labels are visible.

JavaScript
var rangeSliderOptions = {
    label: {
        visible: true,
        position: 'bottom',
        format: function(value) {
            return value + ' units';
        }
    }
}

Show/hide slider tooltip

The widget can also display a tooltip for the slider. The Tooltip options are specified using the tooltip option, which takes an object containing the following properties.

  • enabled
    Specifies whether or not the tooltip is enabled.

  • format
    Specifies a format for the tooltip. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether the tooltip is located over or under the slider, respectively.

  • showMode
    Takes on the 'onHover' or 'always' values, which specify whether the widget shows the tooltip only when the pointer is over the slider or always, respectively.

JavaScript
var rangeSliderOptions = {
    tooltip: {
        enabled: true,
        position: 'bottom',
        showMode: 'always',
        format: function(value) {
            return value + ' units';
        }
    }
}

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Left/right arrow
    Decreases/increases the current handle value by a step.

  • Home/End
    Sets the current handle to the minimum/maximum value.

  • Tab/Shift+Tab
    Switches between handles.

  • Page up/Page down
    Decreases/increases the focused handle value by a value specified using the keyStep option.

dxSelectBox

The dxSelectBox widget is an editor that accepts a value from the list specified by the dataSource option.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

As the widget displays a collection of items, it supports common Collection Container widget functionality and enables you to carry out the following tasks.

In addition to common editor and collection container functionality, the widget enables you to perform the following adjustments.

Tweak For an Item Structure

If a data source item is a string value, the widget uses this value to display the item in the drop-down list and in the text field. This string value is also held in the value option if the item is selected. If a data source item is an object, you should specify which property will be used to display the item and which one will be held in the value option. The displayExpr option specifies the property name whose value will be displayed in the drop-down list and in the text field. To specify the property whose value is held in the value option, assign the required property name to the valueExpr option.

JavaScript
var selectBoxData = [
    { "name": "Alabama", "capital": "Montgomery" },
    { "name": "Alaska", "capital": "Juneau" },
    { "name": "Arizona", "capital": "Phoenix" }
    . . .
]
var selectBoxOptions = {
    dataSource: selectBoxData,
    valueExpr: 'capital',
    displayExpr: 'name'
}

Use the displayValue option to access the text displayed by the text field.

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Alt+Down arrow
    Opens the popup window.

  • Alt+Up arrow
    Closes the popup window.

  • Esc
    Closes the popup window and removes focus from the widget.

  • Up/down arrow (page up/down) If a drop-down list is displayed, this shortcut moves focus to the previous/next item. Otherwise, it switches the current widget value to the previous/next item.

  • Enter (Space) Applies the current item.

dxSlider

The dxSlider widget allows a user to specify a numeric value within a specified range.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Specify the range of available values

The boundaries of the available value range are specified by the min and max options.

JavaScript
var sliderOptions = {
    min: 0,
    max: 100
}

Specify the slider step

The step option specifies the difference between neighboring widget values.

JavaScript
var sliderOptions = {
    step: 10
}

Show/hide labels

The dxSlider widget can display labels for the boundary values. The label options are specified using the label option, which takes on an object containing the following properties.

  • format
    Specifies a format for labels. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether labels are located over or under the scale respectively.

  • visible
    Specifies whether or not slider labels are visible.

JavaScript
var sliderOptions = {
    label: {
        visible: true,
        position: 'bottom',
        format: function(value) {
            return value + ' units';
        }
    }
}

Show/hide slider tooltip

The widget can also display a tooltip for the slider. Tooltip options are specified using the tooltip option, which takes on an object containing the following properties.

  • enabled
    Specifies whether or not the tooltip is enabled.

  • format
    Specifies a format for the tooltip. For more information, refer to the format option description.

  • position
    Takes on the 'top' or 'bottom' values, which specify whether the tooltip is located over or under the slider respectively.

  • showMode
    Takes on the 'onHover' or 'always' values, which specify whether the widget shows the tooltip only when the pointer is over the slider or always respectively.

JavaScript
var sliderOptions = {
    tooltip: {
        enabled: true,
        position: 'bottom',
        showMode: 'onhover',
        format: function(value) {
            return value + ' units';
        }
    }
}

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Left/right arrow
    Decreases/increases the handle value by a step.

  • Home/End
    Sets the handle to the minimum/maximum value.

  • Page up/Page down
    Decreases/increases the handle value by a value specified using the keyStep option.

dxSwitch

The dxSwitch widget is a switch that can have an on or off state.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Specify the text for "enabled" and "disabled" states

The onText and offText options specify the text displayed by the widget when it is in the enabled and disabled states respectively.

JavaScript
var switchOptions = {
    onText: 'On',
    offText: 'Off'
}

Note that the widget does not use text values to identify the state in the iOS and Windows Phone themes.

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Left/right arrow
    decreases/increases the handle value by a step.

  • Home/End
    Sets the handle to the minimum/maximum value.

dxTagBox

The dxTagBox widget is an editor that accepts several values from the list specified by the dataSource option.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

As the widget displays a collection of items, it supports common Collection Container widget functionality and enables you to carry out the following tasks.

In addition to common editor and collection container functionality, the widget enables you to perform the following adjustments.

Access the selected values

You can access the array of the selected values using the values option. The last added value is held in the value option.

Tweak For an Item Structure

If a data source item is a string value, the widget uses this value to display the item in the drop-down list and in the tags field. This string value is also held in the value and values options if the item is selected. If a data source item is an object, you should specify which property will be used to display the item and which one will be held in the value and values options. The displayExpr option specifies the property name whose value will be displayed in the drop-down list and in the tags field. To specify the property whose value is held in the value and values options, assign the required property name to the valueExpr option.

JavaScript
var tagBoxData = [
    { "name": "Alabama", "capital": "Montgomery" },
    { "name": "Alaska", "capital": "Juneau" },
    { "name": "Arizona", "capital": "Phoenix" }
    . . .
]
var tagBoxOptions = {
    dataSource: selectBox0Data,
    valueExpr: 'capital',
    displayExpr: 'name'
}

Use the displayValue option to access the text displayed by the tags field.

Keyboard support

An end-user can use the following keys to interact with the widget.

  • Alt+Down arrow
    Opens the popup window.

  • Alt+Up arrow
    Closes the popup window.

  • Esc
    Closes the popup window and removes focus from the widget.

  • Up/down arrow (page up/down) Moves to the previous/next item.

  • Enter (Space) Applies the current item.

  • Backspace
    Unselects the last selected item.

dxTextArea

The dxTextArea widget enables a user to enter and edit multi-line text.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Limit the number of typed characters

The widget allows you to limit the number of typed characters to the maxLength option value.

JavaScript
var textAreaOptions = {
    maxLength: 100
}

dxTextBox

The dxTextBox widget enables a user to enter and edit a single line of text.

View Demo

The widget supports common Editor widget functionality and enables you to carry out the following common tasks described at the beginning of this article.

In addition to common editor functionality, the widget enables you to perform the following adjustments.

Limit the number of typed characters

The widget allows you to limit the number of typed characters to the maxLength option value.

JavaScript
var textBoxOptions = {
    maxLength: 10
}

Specify the widget mode

You can also specify the text box mode using the mode option. This option passes the value to the mode attribute of the underlying <input> element. This option can take on values supported by the mode attribute of the <input> element.

JavaScript
var textBoxOptions = {
    mode: 'password'
}

Masked edit

The dxTextBox widget enables you to specify a mask for the entered string using the mask option. You can also specify mask placeholder character using the maskChar option. The text displayed when a user enters a value, which does not match the mask, is specified using the maskInvalidMessage option.

JavaScript
var textBoxOptions = {
    mask: '+1(999)000-0000',
    maskChar: '#',
    maskInvalidMessage: 'Value does not match pattern'
}

For the full list of built-in mask rules, refer to the mask option description in the API reference.

You can extend the built-in mask functionality by creating custom mask rules. A mask rule is specified as a key-value pair. A key holds a metacharacter. A value specifies which characters are accepted by the metacharacter. You can specify a rule value in any of following ways.

JavaScript
varCustomMaskRules = {
    //a single character
    's': '$',

    //a regular expression
    'h': '/[0..9]|[A..F]/',

    //an array of characters
    'n': ['$', '%', '&', '@'],

    //a function
    'f': function(char) {
        var allowedChars = ['a', 'b', 'c', '$', '_', '.'];
        for(var i = 0; i < allowedChars.length; i++) {
            if (char === allowedChars[i])
                return true;
        }
        return false;
    }
}

Pass an object containing one or more rules to the maskRules option.