dxList

The dxList widget displays specified data source items as a scrollable list.

View Demo

Default Item Template

The dxList widget displays items stored in a data source specified using the dataSource configuration option. In a simple case, the widget uses the default template to render items. This template represents a list item as a <div> element containing the text associated with the corresponding data item. The default item template can be used if a data source item is a string value, or an object containing the text field, which contains the text associated with this item.

See Also

If data item objects have another structure, you should specify the custom template used to render items.

See Also

Data Shaping

Usually the DataSource instance used by the dxList widget to access data supports data shaping (sorting, filtering, grouping, etc.). The dxList widget includes special features for the following kinds of data shaping.

Grouping

The dxList widget can display data source items as a grouped list. In this case, items of each group are displayed under the group caption. Set the grouped option to true to display a grouped list.

The default group template supports the following array structure.

JavaScript
var listData = [
    {
        key: "group1 caption",
        items: [
            { text: "item1" },
            { text: "item2" },
            { text: "item3" }
        ]
    },
    {
        key: "group2 caption",
        items: [
            { text: "item1" },
            { text: "item2" },
            { text: "item3" }
        ]
    },
    {
        key: "group3 caption",
        items: [
            { text: "item1" },
            { text: "item2" },
            { text: "item3" }
        ]
    }
];

The key property value is displayed as a group header. Group items specified by the items array are displayed below.

If a group header is specified by a different property, you should specify a custom group template in the same way as a custom item template.

JavaScript
var listData = [
    {
        groupName: "A",
        items: [
            { text: "Alabama" },
            { text: "Alaska" },
            { text: "Arizona" },
            { text: "Arkanzas" }
        ]
    },
    {
        groupName: "C",
        items: [
            { text: "California" },
            { text: "Colorado" },
            { text: "Connecticut" }
        ]
    },
    . . .
];

You can render group elements using a custom rendering function. For this purpose, assign the required function to the groupTemplate option. Note that the function should not return a value.

The dxList widget passes the following arguments to the group rendering function.

  • groupData
    The group object to be rendered.
  • groupIndex
    The index of the group header to be rendered.
  • groupElement
    An HTML element of the group header to be rendered.
JavaScript
$("#listContainer").dxList({
        dataSource: listData,
        groupTemplate: function(groupData, groupIndex, groupElement){
            groupElement.empty();
            groupElement.append("<h1 style="\color:red\">" + groupData.groupName + "</h1>");
        }
    });
});

In MVVM approach, to specify a group header structure.

  1. Create an HTML container element within the widget and apply the data-options attribute set to dxTemplate.

    Angular Approach
    HTML
    <div dx-list="{ dataSource: listData }" dx-item-alias="itemObj">
        <div data-options="dxTemplate:{ name:'item' }">
        </div>
    </div>
    Knockout Approach
    HTML
    <div data-bind="dxList:{ dataSource: listData, grouped: true }">
        <div data-options="dxTemplate:{name:'group'}">
        </div>
    </div>
  2. Insert the required structure in the newly added dxTemplate element.

    Angular Approach
    HTML
    <div dx-list="{ dataSource: listData }" dx-item-alias="itemObj">
        <div data-options="dxTemplate:{ name:'item' }">
            <h1 style="color:red;">{{itemObj.groupName}}...</h1>
        </div>
    </div>
    Knockout Approach
    HTML
    <div data-bind="dxList:{ dataSource: listData, grouped: true }">
        <div data-options="dxTemplate:{ name:'group' }">
            <h1 style="color:red;"><span data-bind="text: groupName"></span>...</h1>
        </div>
    </div>

    The default name of the template element is "group". If you use a different template name, assign it to the groupTemplate configuration option of the widget.

    Angular Approach
    HTML
    <div dx-list="{ dataSource: listData, groupTemplate:'myGroup' }" dx-item-alias="itemObj">
        <div data-options="dxTemplate:{ name:'myGroup' }">
            ...
        </div>
    </div>
    Knockout Approach
    HTML
    <div data-bind="dxList:{ dataSource: listData, groupTemplate:'myGroup' }">
        <div data-options="dxTemplate:{ name:'myGroup' }">
            ...
        </div>
    </div>

In addition, the widget supports group collapsing. Assign true to the collapsibleGroups option to enable the feature. In this case, the down arrow is displayed to the right of a group header. An end-user can collapse or expand a group by clicking the group header.

JavaScript
var listOptions = {
    dataSource: listData,
    grouped: true,
    collapsibleGroups: true
}

You can also collapse and expand groups programmatically using the collapseGroup(groupIndex) and expandGroup(groupIndex) methods respectively.

JavaScript
// Get widget instance
. . .
collapseListGroup = function(index){
    listInstance.collapseGroup(index);
}

expandListGroup = function(index){
    listInstance.expandGroup(index);
}

Paging

The dxList widget can display data source items by pages. You can modify paging options using the DataSource instance associated with the widget.

JavaScript
var listData = new DevExpress.data.DataSource({
    store: [ . . . ], //Specifies data associated with the DataSource instance
    paginate: true, //Specifies whether or not DataSource loads data by pages
    pageSize: 10 //Specifies the number of items contained in a single page
});
var listOptions = {
    dataSource: listData
};

The widget includes the following means used to simplify working with paged data.

  • Page load modes

    If the data source associated with the widget loads data by pages, the dxList widget can automatically add a new page to the end of the list each time the list is scrolled to the bottom or when a user clicks the "next" button, depending on the pageLoadMode option value.

    JavaScript
    //load next page when the list is scrolled to the bottom
    var listOptions = {
        dataSource: listData,
        pageLoadMode: "scrollBottom"
    };
    
    
    //load next page when the next button clicked
    var listOptions = {
        dataSource: listData,
        pageLoadMode: "nextButton"
    };
  • Refreshing the list

    If the list data is displayed by pages, an end-user can refresh the list (clear and load the first page) by the "Pull down to refresh" gesture. You can specify feature availability using the pullRefreshEnabled option.

    JavaScript
    var listOptions = {
        dataSource: listData,
        pullRefreshEnabled: true
    };

End User Interaction With Items

The dxList widget enables an end user to perform the following operations on items.

Select Items

The dxList widget allows an end-user to select single or multiple items depending on the selectionMode option value, which supports the "none", "single" and "multi" values.

JavaScript
var listOptions = {
    dataSource: listData,
    selectionMode: "multi"
};

The showSelectionControls option enables you to display check boxes or radio buttons at items if the selectionMode value is "multi" or "single" respectively.

JavaScript
var listOptions = {
    dataSource: listData,
    selectionMode: "multi",
    showSelectionControls: true
};

You can access the list of the selected items using the selectedItems option. If no items are selected, the option contains an empty array.

Handle Selection Events

The widget allows you to handle events that occurred when an item is selected or unselected. Declare the appropriate handling function and assign it to the onSelectionChanged configuration option.

JavaScript
var selectionChanged = function(e) {
    //Process item selection
};

var listOptions = {
    dataSource: listData,
    selectionMode: "single",
    onSelectionChanged: selectionChanged
};

An object passed to the handling function as an argument contains properties that enable you to access the widget instance, widget element, current viewModel, item data object and item element.

Reorder Items

The dxList widget supports the reordering of items by an end-user. Set the allowItemReordering option to true to allow a user to reorder items. To change an item position, drag the required item by the special icon located at the right side of the item and drop it over the target position.

JavaScript
var listOptions = {
    dataSource: listData,
    allowItemReordering: true
};

NOTE: The item reordering feature requires the useNativeScrolling option to be set to false in Windows Phone 8 and Android.

See Also

Item Context Menu

An end-user can call a context menu for a list item. The menu items are specified using the menuItems option. The context menu is available if the menuItems option includes an array containing at least one item.

The menuMode option specifies the way an end-user calls the context menu for an item. This option can take on one of the following values.

  • "context"
    The context menu appears if a user holds the required item. In this case, the context menu may include the "Delete" item in addition to the specified items if item deletion is enabled and the itemDeleteMode option is set to "context".

  • "slide"
    A user swipes the required item to uncover the More button, which calls the context menu.

JavaScript
var listOptions = {
    dataSource: listData,
    menuItems: contextMenuItems,
    menuType: "hold"
};

An array passed to the menuItems option should contain objects including the following properties.

  • text
    Specifies the menu item text.

  • action
    Takes on a function called when the item is clicked (tapped). The function passed to this property has the itemElement and itemData parameters used to access the element and the data object of a list item for which the context menu is called.

JavaScript
var contextMenuItems = [
    {
        text: "Show on the map",
        action: function (itemElement, itemData) {
            //Action implementation
        }
    },
    {
        text: "Show info",
        action: function (itemElement, itemData) {
            //Action implementation
        }
    },
    {
        text: "Edit info",
        action: function (itemElement, itemData) {
            //Action implementation
        }
    }
];

Delete Items

The dxList widget allows an end-user to delete items. To enable deletion, set the allowItemDeleting option to true.

JavaScript
var listOptions = {
    dataSource: listData,
    allowItemDeleting: true
}

You can specify the way an end-user can delete a required item using the itemDeleteMode option. This option can take on one of the following values.

  • "static"
    The Delete button is always displayed by each item. When an end-user clicks the Delete button, the corresponding item is deleted immediately without confirmation.

  • "toggle"
    A user can toggle Delete button visibility by clicking the appropriate icon, located to the left of the required item.

  • "slideButton"
    The "Delete" button slides out the screen when a user swipes the item.

  • "slideItem"
    The item slides left and uncovers the Delete button when a user swipes the item.

  • "swipe"
    A user can delete an item by just swiping it.

  • "context"
    The widget adds the Delete item to the context menu called when the list item is held.

JavaScript
var listOptions = {
    dataSource: listData,
    allowItemDeletion: true,
    itemDeleteMode: "toggle"
}

Scrolling

If list content height exceeds the widget height, an end user can scroll content vertically to view the required item.

Scrolling is enabled by default. However, you can set the enableScrolling option to false to disable it.

If scrolling is enabled, you can specify whether or not a user can scroll the widget by content and by a scroll bar thumb using the scrollByContent and scrollByThumb options respectively.

JavaScript
var listOptions: {
    . . .
    scrollByThumb: true,
    scrollByContent: true
}

The dxList widget also enables you to scroll its content programmatically using the scrollBy(distance), scrollTo(location), scrollToItem(itemElement), scrollToItem(itemIndex) or scrollTop() method.

JavaScript
// Get widget instance
. . .
listInstance.scrollToItem(15);

In addition, you can execute a custom action once the list has been scrolled. Handle the scroll event or pass the required function to the onScroll option.

See Also

Indicate Data Loading

The dxList widget can display the loading panel when it is loading data. Set the indicateLoading option to true to enable this feature.

JavaScript
var listOptions = {
    dataSource: new DevExpress.data.DataSource(myDataStore),
    indicateLoading: true
}

NOTE: This option affects only the load panel displayed when the bound DataSource is loading data after the load() method is called. The load indicator displayed when the list is being updated is always enabled regardless of the option value.

Keyboard Support

An end-user can use the following keys to interact with the widget.

  • Up/down arrow
    Highlight the previous/next item.

  • Page up/page down
    Highlights the item located a page above/below the current one.

  • Home/End
    Highlight the first/last element.

  • Enter (Space)
    Select the current element.

  • Delete
    Remove the current item. Available if the allowItemDeleting option is set to true.

  • Shift + up/down arrow
    Transpose the current and previous/next items. Available if the allowItemReordering option is set to true.