List Configuration

An object defining configuration options for the dxList widget.

activeStateEnabled

A Boolean value specifying whether or not the widget changes its state when interacting with a user.

Type: Boolean
Default Value: true

This option is used when the widget is displayed on a platform whose guidelines include the active state change for widgets.

Show Example:
jQuery
<div data-bind="dxList: { dataSource: listDataSource, activeStateEnabled: enableActiveState, height: '80%' }">
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <p style="font-size:larger;"><b data-bind="text: name"></b></p>
    <p>Capital: <i data-bind="text: capital"></i></p>
  </div>
</div>
<div style="margin-top: 15px;" class="dx-fieldset">
  <div class="dx-field">
    <div class="dx-field-label">Active state</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: enableActiveState }"></div>
  </div>
</div>
enableActiveState = ko.observable(true);

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");
body{
  text-align: center;
}

autoPagingEnabled

A Boolean value specifying whether or not to load the next page from the data source when the list is scrolled to the bottom.

Type: Boolean
Default Value: true
Default for desktop: false

You can also load the next page's data on the "More" button click. Assign true to the showNextButton option to show the "more" button.

Show Example:
jQuery
<div class="list" data-bind="dxList: {
  dataSource: listDataSource,
  autoPagingEnabled: autoPaging,
  showNextButton: nextButton,
  pullRefreshEnabled: true,
  height: '65%'
}">
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width: 70%" class="dx-field-label">Auto paging</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: autoPaging }"></div>
  </div>
  <div class="dx-field">
    <div style="width: 70%" class="dx-field-label">Show Next button</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: nextButton }"></div>
  </div>
</div>
autoPaging = ko.observable(true);
nextButton = ko.observable(false);

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource({
    store: [],
    pageSize: 5
});

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

//Generates the path to the required image file
getImagePath = function (name) {
  return "/Content/images/doc/13_2/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};
body{
  text-align: center;
}
.listItem {
  text-align: left;
  padding: 5px;
}
.list{
  margin-bottom: 35px;
}

clickAction

An action performed when a widget is clicked.

Type: Action
Default Value: null

Show Example:
jQuery
<div data-bind="dxButton:{text: 'Click me'}"></div>
<div style="margin: 10px;" data-bind="dxList: {
  dataSource: listDataSource,
  clickAction: processClick
}">
  <div data-options="dxTemplate:{ name:'group' }">
    <h1 data-bind="text: key"></h1>
  </div>
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
processClick = function () {
  DevExpress.ui.dialog.alert("The widget has been clicked", "Action executed");
};

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");

//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";
};
body{
  text-align: center;
}
.listItem {
  text-align: left;
  padding: 5px;
}

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 data-bind="dxList: {
  pullRefreshEnabled:true,
  dataSource: listDataSource,
  height: '75%'
}">
    <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <p>Population</p>
    <div data-bind="dxRangeSlider: { min: 0, max: 40000000, start: minPopulation, end: maxPopulation }"></div>
    <div style="text-align:left;">
      <p>min: <span data-bind="text: minPopulation"></span></p>
      <p>max: <span data-bind="text: maxPopulation"></span></p>
    </div>
  </div>
</div>
minPopulation = ko.observable(0);
maxPopulation = ko.observable(40000000);

//Executed after maxPopulation value has been changed
maxPopulation.subscribe(function () {
    updateValues();
})

//Executed after minPopulation value has been changed
minPopulation.subscribe(function () {
    updateValues();
})

//Specifies filtering conditions and loads data.
updateValues = function () {
    listDataSource.filter([
        ["population", ">", minPopulation()],
        "and",
        ["population", "<", maxPopulation()]
    ]);
    listDataSource.load();
}

//An object passed to the dataSource configuration option of the list
listDataSource = 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++) {
        listDataSource.store().insert(data[i]);
    }
    updateValues();
}, "json");

//Generates the path to the required image file
getImagePath = function (name) {
    return "/Content/images/doc/13_2/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};
body{
  text-align: center;
}
.listItem {
  border-radius: .5em;
  text-align: left;
  padding: 5px;
}

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="list" data-bind="dxList: { disabled: listDisabled, dataSource: listDataSource }">
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <p style="font-size:larger;"><b data-bind="text: name"></b></p>
    <p>Capital: <i data-bind="text: capital"></i></p>
  </div>
</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: listDisabled }"></div>
  </div>
</div>
listDisabled = ko.observable(false);

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");
body{
  text-align: center;
}
.list{
  margin: 10px;
  height: 400px;
}

editConfig

An object used to set configuration options for the dxList's edit mode.

Type: Object

If you make the dxList widget editable, set the required edit mode. For this purpose, use the deleteEnabled and/or selectionEnabled fields of the editConfig configuration object.

The dxList widget comes with several predefined modes for item deletion and selection. You can set the required mode using the deleteMode and/or selectionMode fields of the editConfig configuration object. The predefined modes enclose a specific item appearance and control elements for deletion and selection. You can also specify a custom HTML template for selectable/deletable list items using the itemRender or itemTemplate option of the editConfig configuration object. In this case, the selectItem, deleteItem and unselectItem widget methods will be useful.

Show Example:
jQuery
<div data-bind="dxList:{dataSource: listDataSource, editEnabled: true, editConfig: {selectionMode: 'control', selectionEnabled: true, deleteEnabled: true, deleteMode: 'toggle'}}">
    <div data-options="dxTemplate:{name:'item'}">
        <span data-bind="text: name"></span>
    </div>   
</div>
//An object passed to the dataSource configuration option of the list
listDataSource = 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++) {
        listDataSource.store().insert(data[i]);
    }
    listDataSource.load();
}, "json");

editEnabled

Specifies whether the item list represented by this widget is editable.

Type: Boolean
Default Value: false

When this option is set to true, the item list becomes editable. Once it is editable, list items can be selected or deleted. To set the required edit mode, use the editConfig configuration option.

In addition, items in an editable list can be selected or deleted from code using the selectItem, deleteItem and unselectItem methods.

You can perform certain actions when an item is deleted, selected or deselected. For this purpose, implement an action and assign it to the itemDeleteAction, itemSelectAction or itemUnselectAction configuration option.

grouped

A Boolean value specifying whether or not to display a grouped list.

Type: Boolean
Default Value: false

If this option is set to 'true', the object assigned to the items option should include the key and items properties. The key property specifies the group caption in the list. The items property represents an array listing the group items.

Show Example:
jQuery
<div id="myList" style="margin: 10px;" data-bind="dxList: {
  dataSource: listDataSource,
  grouped: false,
  height: '80%'
}">
  <div data-options="dxTemplate:{ name:'group' }">
    <h1 data-bind="text: key"></h1>
  </div>
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width: 70%" class="dx-field-label">Grouped</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: showGroups }"></div>
  </div>
</div>
showGroups = ko.observable(false);

//Executed after showGroups value has been changed
showGroups.subscribe(function (newValue) {
    var myList = $("#myList").dxList("instance");
    myList.beginUpdate();
    if (newValue)
        listDataSource.group(function (dataItem) {
            return dataItem.name.charAt(0);
        });
    else 
        listDataSource.group("");
    myList.option("grouped", newValue);
    listDataSource.load().done(function () {
        myList.endUpdate();
    });
})

//An object passed to the dataSource configuration option of the list
listDataSource = 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++) {
        listDataSource.store().insert(data[i]);
    }
    listDataSource.load();
}, "json");

//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";
};
body{
  text-align: center;
}
.listItem {
  text-align: left;
  padding: 5px;
}

groupRender

A function rendering a group header.

Type: function
Function parameters:
itemData: Object
An object representing the group to be rendered.
itemIndex: Number
The index of the group to be rendered.
itemElement: Object
An HTML element containing the group to be rendered.
Return Value: String|DOM Node|jQuery
An HTML string, Element, or jQuery object representing the rendered group caption.
Default Value: null

The rendering function should have the following parameters and return an HTML string, element, or jQuery object representing the rendered group.

  • groupData - the data source element representing the rendered group
  • groupIndex - the index of the rendered group
  • groupElement - the HTML element containing the rendered group
Show Example:
jQuery
 <div id="listContainer"></div>
//An object passed to the dataSource configuration option of the list
listDataSource = 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++) {
        listDataSource.store().insert(data[i]);
    }
    listDataSource.group(function (dataItem) {
        return dataItem.name.charAt(0);
    });
    listDataSource.load();
}, "json");

//A function used to render group captions
groupRenderer = function (groupData, groupIndex, groupElement) {
  var result = "<div style=\"display: inline-block\"><h1 style=\"color:red;\">" + groupData.key + "&nbsp;</h1></div>";
  result += "<div style=\"display: inline-block\">(" + groupData.items[0].name;
  if (groupData.items.length > 1)
    result += " - " + groupData.items[groupData.items.length - 1].name;
  result += ")</div>"
  return result;
};

//A function used to render items
itemRenderer = function (itemData, itemIndex, itemElement) {
  var result = "<p style=\"font-size:larger;\"><b>" + itemData.name + "</b></p>\
  Capital: <i>" + itemData.capital + "</i></p>";
  return result;
};

$(function () {
  $("#listContainer").dxList({
    dataSource: listDataSource,
    grouped: true,
    itemRender: itemRenderer,
    groupRender: groupRenderer
  })
});

body{
  text-align: center;
}
#listContainer{
  margin: 10px;
  text-align: left;
}

groupTemplate

The name of the template used to display a group header.

Type: String|function|DOM Node|jQuery
Return Value: String|jQuery
A template name or a template container.
Default Value: "group"

Show Example:
jQuery
<div data-bind="dxList: {
  dataSource: listDataSource,
  grouped: true,
  itemTemplate: 'stateItem',
  groupTemplate: 'statesGroup'
}">
  <div class="listItem" data-options="dxTemplate:{ name:'statesGroup' }">
    <div style="display: inline-block">
      <h1 style="color:red;" data-bind="text: key + '&nbsp;'"></h1>
    </div>
    <div style="display: inline-block" data-bind="text: getBoundaryItems($data)"></div>
  </div>
  <div class="listItem" data-options="dxTemplate:{ name:'stateItem' }">
    <p style="font-size:larger;"><b data-bind="text: name"></b></p>
    <p>Capital: <i data-bind="text: capital"></i></p>
  </div>
</div>
//An object passed to the dataSource configuration option of the list
listDataSource = 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++) {
        listDataSource.store().insert(data[i]);
    }
    listDataSource.group(function (dataItem) {
        return dataItem.name.charAt(0);
    });
    listDataSource.load();
}, "json");

//Returns boundary items of a group
getBoundaryItems = function (groupData) {
  if (groupData.items.length > 1)
    return groupData.items[0].name + " - " + groupData.items[groupData.items.length - 1].name;
  return groupData.items[0].name;
};
body{
  text-align: center;
}
.listItem {
  border-radius: .5em;
  text-align: left;
  padding: 5px;
}

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 + "%"; })

itemClickAction

An action performed when a collection item is clicked.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the following fields besides the basic field set.

  • itemData - Contains an object representing the clicked item
  • itemElement - Contains an HTML element representing the clicked item

itemDeleteAction

An action performed when a list item is deleted.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the following fields in addition to the basic field set.

  • itemData - Contains an object representing the deleted item.
  • itemElement - Contains an HTML element representing the deleted item.

itemHoldAction

An action performed when an item is being held for a specified time period.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the the following fields in addition to the basic field set.

  • itemData - Contains an object representing the item.
  • itemElement - Contains an HTML element representing the item.
Show Example:
jQuery
<div style="margin: 10px;" data-bind="dxList: {
  dataSource: listDataSource,
  itemHoldAction: processItemHold,
  itemHoldTimeout: holdTimeout,
  height:'75%'
}">
  <div data-options="dxTemplate:{ name:'group' }">
    <h1 data-bind="text: key"></h1>
  </div>
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
<p></p>
<div class="dx-fieldset">
  <div class="dx-field">
    <p>Hold timeout</p>
    <div data-bind="dxSlider: { min: 250, max: 2000, value: holdTimeout }"></div>
    <div style="text-align:left;">
      <p>Timeout: <span data-bind="text: holdTimeout"></span></p>
    </div>
  </div>
</div>
holdTimeout = ko.observable(750);

//The itemHold action function
processItemHold = function () {
  DevExpress.ui.dialog.alert("The item is being held during " + holdTimeout() / 1000 + "sec", "Action executed");
}

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");

//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";
};
body{
  text-align: center;
}
.listItem {
  text-align: left;
  padding: 5px;
}

itemHoldTimeout

The time period in milliseconds before itemHoldAction execution.

Type: Number
Default Value: 750

Show Example:
jQuery
<div style="margin: 10px;" data-bind="dxList: {
  dataSource: listDataSource,
  itemHoldAction: processItemHold,
  itemHoldTimeout: holdTimeout,
  height:'75%'
}">
  <div data-options="dxTemplate:{ name:'group' }">
    <h1 data-bind="text: key"></h1>
  </div>
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
<p></p>
<div class="dx-fieldset">
  <div class="dx-field">
    <p>Hold timeout</p>
    <div data-bind="dxSlider: { min: 250, max: 2000, value: holdTimeout }"></div>
    <div style="text-align:left;">
      <p>Timeout: <span data-bind="text: holdTimeout"></span></p>
    </div>
  </div>
</div>
holdTimeout = ko.observable(750);

//The itemHold action function
processItemHold = function () {
  DevExpress.ui.dialog.alert("The item is being held during " + holdTimeout()/1000 + "sec", "Action executed");
}

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");

//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";
};
body{
  text-align: center;
}
.listItem {
  text-align: left;
  padding: 5px;
}

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="listContainer"></div>
//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");

//A function used to render items
itemRenderer = function (itemData, itemIndex, itemElement) {
    var result = "<div style=\"display:inline-block; margin: 5px;\">\
    <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 () {
  $("#listContainer").dxList({
    dataSource: listDataSource,
    itemRender: itemRenderer
  })
});

body{
  text-align: center;
}
#listContainer{
  margin: 10px;
  text-align: left;
}

itemRenderedAction

An action performed after a collection item is rendered.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the following fields in addition to the basic field set.

  • itemData - Contains an object representing the item
  • itemElement - Contains an HTML element representing the item

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.

itemSelectAction

An action performed when a list item is selected.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the following fields in addition to the basic field set.

  • itemData - Contains an object representing the selected item.
  • itemElement - Contains an HTML element representing the selected item.

itemSwipeAction

An action performed when an item is swiped.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the the following fields in addition to the basic field set.

  • itemData - Contains an object representing the item.
  • itemElement - Contains an HTML element representing the item.
  • direction - Specifies the swipe gesture direction. The available values are "horizontal" and "vertical".
Show Example:
jQuery
<div style="margin: 10px;" data-bind="dxList: {
  dataSource: listDataSource,
  itemSwipeAction: processItemSwipe
}">
  <div data-options="dxTemplate:{ name:'group' }">
    <h1 data-bind="text: key"></h1>
  </div>
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
processItemSwipe = function (swipeOptions) {
  DevExpress.ui.dialog.alert("The \"" + swipeOptions.itemData.name + "\" item is swiped", "Action executed");
};

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");

//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";
};
body{
  text-align: center;
}
.listItem {
  text-align: left;
  padding: 5px;
}

itemTemplate

The 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 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 data-bind="dxList: {
  dataSource: listDataSource,
  itemTemplate: 'stateItem'
}">
  <div class="listItem" 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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");

//Generates the path to the required image file
getImagePath = function (name) {
  return "/Content/images/doc/13_2/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};
body{
  text-align: center;
}
.listItem {
  border-radius: .5em;
  text-align: left;
  padding: 5px;
}

itemUnselectAction

An action performed when a list item is deselected.

Type: Action
Default Value: null

An object passed to the action function assigned to this option can have the following fields in addition to the basic field set.

  • itemData - Contains an object representing the deselected item.
  • itemElement - Contains an HTML element representing the deselected item.

nextButtonText

The text displayed on the button used to load the next page from the data source.

Type: String
Default Value: "More"

noDataText

The text displayed by the widget if the item collection is empty.

Type: String
Default Value: "No data to display"

pageLoadingAction

An action performed before loading the next page, when autopaging is enabled.

Type: Action
Default Value: null

pageLoadingText

Specifies the text shown in the pullDown panel, which is displayed when the list is scrolled to the bottom.

Type: String
Default Value: "Loading..."

pulledDownText

Specifies the text displayed in the pullDown panel when the list is pulled below the refresh threshold.

Type: String
Default Value: "Release to refresh..."

pullingDownText

Specifies the text shown in the pullDown panel while the list is being pulled down to the refresh threshold.

Type: String
Default Value: "Pull down to refresh..."

pullRefreshAction

An action performed before the list is refreshed as a result of the "pull down to refresh" gesture.

Type: Action
Default Value: null

pullRefreshEnabled

A Boolean value specifying whether or not the widget supports the "pull down to refresh" gesture.

Type: Boolean
Default Value: false

If the option is set to true, list data is refreshed each time you pull down and release list contents.

NOTE: The "pull down to refresh" gesture is not supported by desktop browsers and Windows Phone devices. You can use it only in mobile themes except the Windows Phone theme.

Show Example:
jQuery
<div class="list" data-bind="dxList: {
  dataSource: listDataSource,
  autoPagingEnabled: true,
  pullRefreshEnabled: pullRefresh,
  height: '75%'
}">
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <p style="font-size:larger;"><b data-bind="text: name"></b></p>
    <p>Capital: <i data-bind="text: capital"></i></p>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width: 80%" class="dx-field-label">Enable pull down to refresh</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: pullRefresh }"></div>
  </div>
</div>
pullRefresh = ko.observable(true);

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource({
    store: [],
    pageSize: 10
});

//Loads json data and passes it to the DataSource
$.get("/Content/data/states.txt", function (data) {
    for (var i = 0; i < data.length; i++) {
        listDataSource.store().insert(data[i]);
    }
    listDataSource.pageIndex(0);
    listDataSource.load();
}, "json");
body{
  text-align: center;
}
.listItem {
  text-align: left;
  padding: 5px;
}
.list{
  margin-bottom: 35px;
}

refreshingText

Specifies the text displayed in the pullDown panel while the list is being refreshed.

Type: String
Default Value: "Refreshing..."

scrollAction

An action performed on each scroll gesture.

Type: Action
Default Value: null

scrollingEnabled

A Boolean value specifying whether to enable or disable list scrolling.

Type: Boolean
Default Value: true

selectedItems

Specifies the selected list items.

Type: Array

To select items when the widget is rendered, set the editEnabled option to true and assign an array with links to the data source items to the selectedItems option.

To determine which items are currently selected, use the widget's option method passing the selectedItems as a parameter.

showNextButton

A Boolean value specifying whether the widget loads the next page automatically when you reach the bottom of the list, or when a button is clicked.

Type: Boolean
Default Value: false
Default for desktop: true

If this option is set to true, the widget shows a "Next Page" button, and loads the next page of data when you click this button. Otherwise, the widget loads the data automatically, each time you reach the bottom of the list.

NOTE: The default value of this option is false if your application is running on a mobile platform. If you run the application on the desktop, the default value is true.

Show Example:
jQuery
<div class="list" data-bind="dxList: {
  dataSource: listDataSource,
  autoPagingEnabled: true,
  showNextButton: nextButton,
  height: '75%'
}">
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <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>
    <p>Area: <i data-bind="text: area"></i> km2</p>
    <p>Population: <i data-bind="text: population"></i></p>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width: 70%" class="dx-field-label">Show Next button</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: nextButton }"></div>
  </div>
</div>
nextButton = ko.observable(false);

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource({
    store: [],
    pageSize: 5
});

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

//Generates the path to the required image file
getImagePath = function (name) {
  return "/Content/images/doc/13_2/PhoneJS/flags/" + name.replace(" ", "") + ".gif";
};
body{
  text-align: center;
}
.listItem {
  border-radius: .5em;
  text-align: left;
  padding: 5px;
}
.list{
  margin-bottom: 40px;
}

showScrollbar

A Boolean value specifying if the widget scrollbar is visible.

Type: Boolean
Default Value: true

Show Example:
jQuery
<div class="list" data-bind="dxList: { showScrollbar: scrollbarVisible, dataSource: listDataSource }">
  <div class="listItem" data-options="dxTemplate:{ name:'item' }">
    <p style="font-size:larger;"><b data-bind="text: name"></b></p>
    <p>Capital: <i data-bind="text: capital"></i></p>
  </div>
</div>
<div class="dx-fieldset">
  <div class="dx-field">
    <div style="width:70%" class="dx-field-label">Show scroll bar</div>
    <div class="dx-field-value" data-bind="dxCheckBox: { checked: scrollbarVisible }"></div>
  </div>
</div>
scrollbarVisible = ko.observable(true);

//An object passed to the dataSource configuration option of the list
listDataSource = new DevExpress.data.DataSource("/Content/data/states.txt");
body{
  text-align: center;
}
.list{
  margin: 10px;
  height: 400px;
}

useNativeScrolling

Specifies whether to use native or simulated scrolling.

Type: Boolean
Default Value: true
Default for android below version 4: false
Default for tizen: false

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 + "%"; })