Configuration

An object defining configuration options for the dxSelectBox widget.

changeAction

An action performed after the change DOM event has been raised for the current input element.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused the action's execution.

Default Value: null

Assign a function to perform a custom action when a change within the widget's input element is committed by an end user.

Alternatively, you can assign a URL to which the browser will navigate when a change within the widget's input element is committed by an end user.

closeAction

An action performed when the drop-down editor is hidden.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

Default Value: null

Assign a function to perform a custom action when the drop-down editor is hidden.

Alternatively, you can assign a URL to which the browser will navigate when the drop-down editor is hidden.

contentReadyAction

An action performed when widget content is ready.

Type: String|function
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

Default Value: null

Assign a function to perform a custom action when widget content is ready.

Alternatively, you can assign a URL to which the browser will navigate when widget content is ready.

If data displayed by the widget is specified using a DataSource instance, the contentReadyAction is executed each time the load() method of the DataSource instance is called as well as when widget content is ready. In this case, when you create the widget, the contentReadyAction is executed twice: when widget content is ready (at this moment, the widget does not display items) and when the DataSource is loaded (the widget displays the loaded items).

copyAction

An action performed when the copy DOM event has been fired.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused the action's execution.

Default Value: null

Assign a function to perform a custom action after the widget's input has been copied.

Alternatively, you can assign a URL to which the browser will navigate after the widget's input is copied.

cutAction

An action performed when the cut DOM event has been fired.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action after the widget's input has been cut.

Alternatively, you can assign a URL to which the browser will navigate after the widget's input is cut.

dataSource

A data source used to fetch data to be displayed by the widget.

Default Value: null

You can assign an array directly to this option as well as use the Data Source provided by the DevExtreme library.

To display widget items, a default template can be used. This template is based on the data source fields that are listed in the Default Item Template section of the widget's API. Alternatively, you can implement a custom item template. For details, refer to the Customize Widget Item Appearance topic.

Show Example:
jQuery

disabled

A Boolean value specifying whether or not the widget can respond to user interaction.

Type: Boolean
Default Value: false

Create an observable variable and assign it to this option to specify the availability of the widget at runtime.

Show Example:
jQuery

displayExpr

Specifies the name of the data source item field whose value is displayed by the widget.

Type: String
Default Value: "this"

If the Autocomplete item is a simple object holding a value (string, numeric, Boolean, etc.), assign 'this' to the displayExpr option. If the item is a plain object item, assign the required field name to the option.

Show Example:
jQuery

displayValue

Contains the text currently displayed by the widget.

Type: String
Default Value: undefined

Show Example:
jQuery

enterKeyAction

An action performed when the Enter key has been pressed.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action after a key has been entered within the widget's input element.

Alternatively, you can assign a URL to which the browser will navigate after a key is entered within the widget's input element.

fieldTemplate

The template to be used for rendering the widget text field.

Type: String|function|DOM Node|jQuery
Return Value: String|jQuery

A template name or a template container.

Default Value: null

This option enables you to render the widget text field depending on the selected item values.

HTML
<div data-options="dxTemplate: { name:'myField' }">
    <div data-bind="dxTextBox { value: $data.name } "></p>
</div>

The $data variable available within the template contains the data model object bound to the current view.

Show Example:
jQuery

focusInAction

An action performed when the focusin DOM event has been raised for the current input element.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action after the widget's input has been focused.

Alternatively, you can assign a URL to which the browser will navigate after the widget's input is focused.

focusOutAction

An action performed when the focusout DOM event has been raised for the current input element.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action after the widget's input element has lost focus.

Alternatively, you can assign a URL to which the browser will navigate after the widget's input element loses focus.

height

Specifies the height of the widget.

Type: Number|String|function
Return Value: Number|String

The widget height.

Default Value: undefined

The option can hold a value of the following types.

  • numeric
    The widget height in pixels.
  • string
    A CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit").
  • function
    The function returning the widget height. For example, see the following code.

    JavaScript
    height: function () { 
        return baseHeight - 10 + "%";
    }

hoverStateEnabled

A Boolean value specifying whether or not the widget changes its state when being hovered by an end user.

Type: Boolean
Default Value: true

inputAction

An action performed when the input DOM event has been fired.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action when a value within the widget's input element is changed by an end user.

Alternatively, you can assign a URL to which the browser will navigate when a value within the widget's input element is changed by an end user.

itemRender

A function used to render collection items.

Type: function
Function parameters:
itemData: Object

The data that is bound to the rendred item.

itemIndex: Number

The index of the item to be rendered.

itemElement: jQuery

An HTML element of the item to be rendered.

Return Value: String|DOM Node|jQuery

An HTML string, Element, or jQuery object representing the rendered item.

Default Value: null

As in all container widgets in DevExtreme, items of this widget are displayed by a default HTML template. This template is based on certain fields of the data source. You can define a custom item template that will use specific fields of the data source. To learn more about item templates, refer to the Customize Widget Item Appearance topic.

Implement the itemRender function to provide a custom item template for a given collection item. This function is called each time a collection item of the widget is rendered. The following data is passed as function parameters.

  1. itemData - An object representing the rendered item.
  2. itemIndex - An index of the rendered item.
  3. itemElement - A container element containing the rendered item.

Return an HTML string, Element, or jQuery object representing the rendered item.

Alternatively, you can define the dxTemplate markup component within the widget element and set its name option to item. In this case, the markup enclosed into the dxTemplate component will be automatically applied as an item template. In addition, you may need to define several item templates and apply each of them when required. In this instance, use the itemTemplate option to set the required template.

Refer to the Customize Widget Item Appearance topic to learn more about ways to render collection items.

Show Example:
jQuery

items

An array of items displayed by the widget.

Type: Array

You can use the dataSource option instead. Unlike the items option, the dataSource option can take on the DataSource configuration object as well as a simple array.

itemTemplate

A template to be used for rendering items.

Type: String|function|DOM Node|jQuery
Return Value: String|jQuery

A template name or a template container.

Default Value: "item"

As in all container widgets in DevExtreme, items of this widget are displayed in a default HTML template. This template is based on certain fields of the data source. You can define a custom item template that will use specific fields of the data source. To learn more about item templates, refer to the Customize Widget Item Appearance topic.

In a simple case, you can define a single custom template for widget items using the dxTemplate markup component within the widget's container. Set the name option of this component to 'item'. In this instance, this template will be automatically used as an item template, and you don't have to specify the itemTemplate option.

However, in some cases you may need to have several custom item templates defined within the widget's container and apply each of them in different scenarios. In this instance, use one of the following ways of setting the required template to the itemTemplate option.

  • Assign a string representing the name of the required template.
  • Assign a function that returns the name of the template as a result of a certain logic.

When you have several collection widgets, you may need to define a common template for them. For this purpose, factor out a template into a separate element, as demonstrated below.

HTML
<script type="text/html" id="person-template">
    <h3 data-bind="text: name"></h3>
    <p>Address: <span data-bind="text: address"></span></p>
</script>

To set the common template as a collection item template, assign one of the following values to the itemTemplate option.

  • Assign a jQuery object representing the template's container.
  • Assign a DOM Node representing the template's container.
  • Assign a function that returns the jQuery object or a DOM Node representing the template's container.
Show Example:
jQuery

keyDownAction

An action performed when the keydown DOM event has been raised for the current input element.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action when a key is pressed down within the widget's input element.

Alternatively, you can assign a URL to which the browser will navigate when a key is pressed down within the widget's input element.

keyPressAction

An action performed when the keypress DOM event has been raised for the current input element.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action when the keypress DOM event has been raised for the current input element.

Alternatively, you can assign a URL to which the browser will navigate when the keypress DOM event has been raised for the current input element.

keyUpAction

An action performed when the keyup DOM event has been raised for the current input element.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action when a key is released within the widget's input element.

Alternatively, you can assign a URL to which the browser will navigate when a key is released within the widget's input element.

maxLength

Specifies the maximum number of characters you can enter into the input text box.

Type: String|Number
Default Value: null

If the number of entered characters reaches the value assigned to this option, the widget does not allow you to enter any more characters.

mode

The "mode" attribute value of the actual HTML input element representing the text box.

Type: String
Default Value: "text"
Accepted Values: 'text'|'email'|'search'|'tel'|'url'|'password'

The value of this option affects the set of keyboard buttons shown on the mobile device when the widget gets focus. In addition, the following mode values add visual features to the widget:

  • 'search' - the text box contains the 'X' button, which clears the text box contents
  • 'password' - the text box shows a password character instead of the actual characters typed

multiSelectEnabled

Specifies whether the widget supports multi-selection.

Type: Boolean
Default Value: false

Use the values option to access the array of selected items.

Show Example:
jQuery

openAction

An action performed when the drop-down editor is shown.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

Default Value: null

Assign a function to perform a custom action when the drop-down editor is shown.

Alternatively, you can assign a URL to which the browser will navigate when the drop-down editor is shown.

pasteAction

An action performed when the paste DOM event has been fired.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: null

Assign a function to perform a custom action after the widget's input has been pasted.

Alternatively, you can assign a URL to which the browser will navigate after the widget's input is pasted.

placeholder

The text that is provided as a hint in the select box editor.

Type: String
Default Value: "Select"

readOnly

A Boolean value specifying whether or not the widget is read-only.

Type: Boolean
Default Value: false

rtlEnabled

Specifies whether or not the current component supports a right-to-left representation.

Type: Boolean
Default Value: false

If you need to switch the display of this DevExtreme component to right-to-left, enable a specifically designed configuration option - rtlEnabled. When this option is set to true, the text flows from right to left, and the layout the component's elements is reversed. To switch the entire application/site to a right-to-left representation, use the static DevExpress.rtlEnabled field.

value

The currently selected value in the widget.

Type: String
Default Value: undefined

If select box items represent objects, the value option returns the value of the specified field of the currently selected item object. The field whose value is returned by the value option is specified via the valueExpr option.

If the multiSelectEnabled option is set to true, you can access all selected items via the values option. In this case, the value option contains only the last selected item.

Show Example:
jQuery

valueChangeAction

An action performed when the editor value changes.

Type: String|function(e)
Function parameters:

Provides function parameters.

Object structure:
component: Object

Provides access to the widget instance.

element: jQuery

An HTML element of the widget.

model: Object

Provides access to the data that is available for binding against the element.

value: Object

Returns the widget's new value.

previousValue: Object

Returns the widget's previous value.

jQueryEvent: jQuery.Event

Specifies the jQuery event that caused action execution.

Default Value: undefined

Assign a function to perform a custom action when the editor value changes.

Alternatively, you can assign a URL to which the browser will navigate when the editor value changes.

Show Example:
jQuery

valueChangeEvent

Specifies DOM event names that update a widget's value.

Type: String
Default Value: "change"

The option takes on a string value representing a DOM event name or several DOM event names separated by a space. You can assign any DOM event name to this option. For example, "change", "blur", "input", "keyup", etc.

valueExpr

Specifies the name of a data source item field whose value is held in the value configuration option.

Type: String
Default Value: null

Assign "this" to this option in order for the widget to return the entire selected object from the value option.

Show Example:
jQuery

values

An array of selected values.

Type: Array

This option makes sense only if the multiSelectEnabled option is set to true. If multi-selection is disabled, the option contains an empty array.

Show Example:
jQuery

visible

A Boolean value specifying whether or not the widget is visible.

Type: Boolean
Default Value: true

width

Specifies the width of the widget.

Type: Number|String|function
Return Value: Number|String

The widget width.

Default Value: undefined

The option can hold a value of the following types.

  • numeric
    The widget width in pixels.
  • string
    A CSS measurement of the widget width (e.g., "55px", "80%", "auto" and "inherit").
  • function
    The function returning the widget width. For example, see the following code.

    JavaScript
    width: function () { 
        return baseWidth - 10 + "%";
    }