List

A list widget.

Type: Object

The dxList widget displays selected items as a scrollable list. To create the dxList widget, add a div element with dxList binding within the body of the required view.

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

NOTE: By default, dxList has a height that is 100% equivalent to that 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.

JavaScript
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 the list item is disabled.
  • visible
    Specifies whether 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.

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.

HTML
<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>  
    <div data-options="dxTemplate: { name: 'item' }">
        <span data-bind="text: name"></span> (hired at <span data-bind="text: hired"></span>)
    </div>   
</div>

Refer to the Add a Widget documentation section to learn how to create widgets in detail.

Show Example:
jQuery

Configuration

An object defining configuration options for the dxList widget.

Methods

This section describes members used to manipulate the widget.

Events

This section describes events fired by this component.