SelectBox Configuration

An object defining configuration options for the dxSelectBox widget.

clickAction

An action performed when a widget is clicked.

Type: Action
Default Value: null

Show Example:
jQuery
<div class="selectbox" data-bind="dxSelectBox: {
    dataSource: selectBoxDataSource,
    clickAction: processClick,
    displayExpr: 'name',
    placeholder: 'Click here'        
}">
</div>
processClick = function () {
  DevExpress.ui.notify("The widget has been clicked", "info", 1000);
};

//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");
body{
  text-align: center;
}
.selectbox{
  margin: 10px;
}

contentReadyAction

An action performed when widget content is ready.

Type: Action
Default Value: null

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 Layer provided by the PhoneJS library.

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

Show Example:
jQuery
<div class="selectbox" data-bind="dxSelectBox: {
    dataSource: selectBoxDataSource,
    displayExpr: 'name',
    placeholder: 'Type a state name'
}">
</div>
//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");
body{
  text-align: center;
}
.selectbox{
  margin: 10px;
}

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
<div class="selectbox" data-bind="dxSelectBox: {
    dataSource: selectBoxDataSource,
    disabled: selectBoxDisabled,
    displayExpr: 'name',
    placeholder: 'Type a state name'
}">
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Disabled</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: selectBoxDisabled }"></div>
  </div>
</div>
selectBoxDisabled = ko.observable(false);

//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");
body{
  text-align: center;
}
.selectbox{
  margin: 10px;
}

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
 <div class="selectbox" data-bind="dxSelectBox: {
    dataSource: selectBoxDataSource,
    displayExpr: currentDisplayExpr,
    placeholder: 'Type here'
}">
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">displayExpr</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: { dataSource: fields, value: currentDisplayExpr }"></div>
  </div>
</div>
fields = ["name", "capital", "population", "area"];
currentDisplayExpr = ko.observable(fields[0]);

//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");
body{
  text-align: center;
}
.selectbox{
  margin: 10px;
}

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 the following types of values.

  • numeric - the height of the widget in pixels
  • string - a CSS measurement of the widget height (e.g., "55px", "80%", "auto" and "inherit")
  • function - a function returning the widget height (e.g., height:function(){ return baseHeight - 10 + "%"; })

itemRender

A function used to render collection items.

Type: function
Function parameters:
itemData: Object
An object representing the item to be rendered.
itemIndex: Number
The index of the item to be rendered.
itemElement: Object
An HTML element containing 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 PhoneJS, 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
 <div id="selectBoxContainer"></div>
//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");

//A function used to render items
itemRenderer = function (itemData, itemIndex, itemElement) {
    var result = "<div style=\"display:inline-block; margin: 5px; text-align:left;\">\
    <img src=\"" + getImagePath(itemData.name) + "\"/>\
    </div>\
    <div style=\"display:inline-block; margin: 5px;\">\
    <p style=\"font-size:larger;\"><b>" + itemData.name + "</b></p>\
    Capital: <i>" + itemData.capital + "</i></p>\
    </div>";
    return result;
};

//Generates the path to the required image file
getImagePath = function (name) {
    if (name === undefined)
        return;
    return "/Content/images/doc/13_2/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};

$(function () {
    $("#selectBoxContainer").dxSelectBox({
        dataSource: selectBoxDataSource,
        itemRender: itemRenderer,
        displayExpr: 'name'
    })
});
body{
  text-align: center;
}
#selectBoxContainer{
  margin: 10px;
}

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: null

As in all container widgets in PhoneJS, 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.

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
<div class="selectbox" data-bind="dxSelectBox: {
    dataSource: selectBoxDataSource,
    itemTemplate: 'stateItem',
    displayExpr: 'name'
}">
  <div class="lookupItem" data-options="dxTemplate:{ name:'stateItem' }">
    <div style="display:inline-block; margin: 5px;">
      <img style="margin:5px;" data-bind="attr: { src: getImagePath(name) }" />
    </div>
    <div style="display:inline-block; margin: 5px;">
      <p style="font-size:larger;"><b data-bind="text: name"></b></p>
      <p>Capital: <i data-bind="text: capital"></i></p>
    </div>
  </div>
</div>
//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");

//Generates the path to the required image file
getImagePath = function (name) {
  if (name !== undefined)
    return "/Content/images/doc/13_2/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};
body{
  text-align: center;
}
.selectbox{
  margin: 10px;
}

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.

placeholder

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

Type: String
Default Value: "Select"

value

The value currently selected 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.

Show Example:
jQuery
<div class="selectbox" data-bind="dxSelectBox: {
    placeholder: 'Select state',
    dataSource: selectBoxDataSource,
    displayExpr: 'name',
    value: value,
    valueExpr: 'capital'
}">
</div>
<div class="dx-fieldset">
    <div class="dx-field">
        <div class="dx-field-label">Capital</div>
        <div class="dx-field-value" data-bind="dxTextBox: { value: value }"></div>
    </div>
</div>
value = ko.observable("");

//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");
body{
  text-align: center;
}
.selectbox{
  margin: 10px;
}

valueChangeAction

An action performed when the value of the widget is changed.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the value field in addition to the basic field set. This field contains the new widget value.

Show Example:
jQuery
<div class="selectbox" data-bind="dxSelectBox: {
    dataSource: selectBoxDataSource,
    valueChangeAction: processValueChange,
    displayExpr: 'name',
    placeholder: 'Click here'        
}">
</div>
processValueChange = function () {
  DevExpress.ui.notify("The widget value has been changed", "info", 1000);
};

//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");
body{
  text-align: center;
}
.selectbox{
  margin: 10px;
}

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
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:auto;" data-bind="dxSelectBox: {
        dataSource: selectBoxDataSource,
        displayExpr: 'name',
        valueExpr: valueExprValue,
        value: currentValue
    }"></div>
  </div>
    <div class="dx-field">
        <div style="width:60%;" class="dx-field-label">Value</div>
        <div style="width:auto;" class="dx-field-value" data-bind="text: currentValue"></div>
    </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:60%;" class="dx-field-label">valueExpr</div>
    <div style="width:auto;" class="dx-field-value" data-bind="dxLookup: { dataSource: fields, value: valueExprValue }"></div>
  </div>
</div>

currentValue = ko.observable("none");
fields = ["this", "name", "capital", "population", "area"];
valueExprValue = ko.observable(fields[1]);

//An object passed to the dataSource configuration option of the select box
selectBoxDataSource = new DevExpress.data.DataSource([]);

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        selectBoxDataSource.store().insert(data[i]);
    }
    selectBoxDataSource.load();
}, "json");

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 the following types of values.

  • 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 (e.g., width:function(){ return baseWidth - 10 + "%"; })