A list widget.

Included in: dx.phonejs.js, dx.webappjs.js, dx.all.js
Type: Object

The dxList widget displays selected items as a scrollable list.

This widget, like any other DevExtreme UI widget, can be created using one of three possible approaches: jQuery, Knockout or AngularJS. The following code demonstrates how to create the dxList widget using the Knockout approach.

<div data-bind="dxList: { dataSource: employees, grouped: true }"></div>

NOTE: By default, dxList has a height that is 100% of the container. When you place a list on your view, the view content is a container for your list and the dxList stretches according to the view content height. This does not create issues for list content visualization. However, if the view has an extra element(s) in addition to the dxList widget, the total height of the view content will be more than it is, because of the default list height. This will lead to a problem with list scrolling. To solve this, specify a height for the dxList widget so that the total height of the view elements equals the view content height. Use any means you like for the solution (e.g., css rules, the height option, etc.).

The list items are loaded from an array specified using the dataSource configuration option. You can specify a simple array or the array of objects as the widget data source to display list items in a single list. If you want the widget to display a grouped list, assign true to the grouped configuration option. The data source array for a grouped list should appear as follows.

var employees = [
        key: 'Management',
        items: [
            { name: "Bob", hired: 2005 },
            { name: "John", hired: 2007 },
            { name: "Frank", hired: 2001 },
            { name: "Robert", hired: 2007 }
        key: 'Manufacturing',
        items: [
            { name: "Paul", hired: 2011 },
            { name: "Elizabeth", hired: 2000 },
            { name: "Mary", hired: 2002 },
            { name: "Michael", hired: 2003 },
            { name: "George", hired: 2002 }
        key: 'Sales',
        items: [
            { name: "Deborah", hired: 2000 },
            { name: "Lisa", hired: 1999 },
            { name: "Mark", hired: 2011 },
            { name: "Joseph", hired: 2000 }

Each key item field value represents a group title. The group items are listed in the items array.

To display list items, a default template is applied based on the following fields of the data source item objects.

  • disabled
    Specifies whether or not the list item is disabled.
  • visible
    Specifies whether or not the list item is visible.
  • html
    Specifies the html code inserted into the item element.
  • text
    Specifies the text inserted into the item element.
  • key
    Specifies the name of the list items group.

To learn more about the fields used in the default item template, refer to the Default Item Template reference section of the widget.

At the same time, it is enough to specify a simple array as a widget data source. In this instance, a default item template includes only the text binding to the current array value.

You can introduce custom templates for list groups and items. For this purpose, add a div element with the data-options attribute set to dxTemplate. Provide a name for the template using the name option. Set the group name for the group template and the item name for the item template. In this instance, these templates will be applied automatically. See the Customize Widget Item Appearance topic to learn more about templates.

<div data-bind="dxList: { dataSource: employees, grouped: true }">
    <div data-options="dxTemplate: { name: 'group' }">
        <b><span data-bind="text: key"></span></b> (<span data-bind="text: items.length"></span>)
    <div data-options="dxTemplate: { name: 'item' }">
        <span data-bind="text: name"></span> (hired at <span data-bind="text: hired"></span>)
See Also
  • To learn how to create widgets in detail, refer to the Create a Widget article.
  • The dxList widget is related to the Collection Containers category. So read an overview of the features that are common for collection container widgets in the Common Tasks topic of the Collection Containers article.
Show Example:


An object defining configuration options for the dxList widget.


This section describes members used to manipulate the widget.


This section describes events fired by this component.

Default Item Template

This section lists the data source fields that are used in a default template for list items.

By default, a predefined item template is applied to display items of DevExtreme collection widgets. This template is based on certain fields of the data source provided for a widget. Below is the list of the fields that take part in a default item template for the dxList widget. If the default item template is not appropriate for your task, implement a custom item template based on these or other fields of your data source. For details refer to the Customize Widget Item Appearance topic.