List

The List is a widget that represents a collection of items in a scrollable list.

Included in: dx.mobile.js, dx.web.js, dx.viz-web.js, dx.all.js
Module: ui/list
List interactive configuration
Copy Code
Copy to Codepen
$("#list").dxList({
});

                    
Type:

Object

You can create the widget using one of the following approaches.

  • jQuery
    Use the dxList jQuery plug-in.

    HTML
    <div id="list"></div>
    JavaScript
    $("#list").dxList({
        dataSource: listData,
        grouped: true,
        showDeleteControls: true,
        showReorderControls: true,
        showSelectionControls: true
    });
  • Knockout
    Add a div element and apply the dxList binding to this element.

    HTML
    <div data-bind="dxList: {
        dataSource: listData,
        grouped: true,
        showDeleteControls: true,
        showReorderControls: true,
        showSelectionControls: true
    }"></div>
  • AngularJS
    Add a div element and apply the dx-list directive to this element.

    HTML
    <div dx-list="{
        dataSource: listData,
        grouped: true,
        showDeleteControls: true,
        showReorderControls: true,
        showSelectionControls: true
    }"></div>

Note that DevExtreme widgets require you to link the jQuery library to your application. If you use the Knockout or AngularJS approach, the Knockout or AngularJS library is also required. For detailed information on linking these libraries to your project, refer to the Installation article.

The List widget supports common Collection Container functionality. You can find detailed information on the principles of working with collection container widgets in the Collection Container Widgets guide. For detailed information on working with the List widget, refer to the dxList guide.

View Demo

Configuration

An object defining configuration options for the List widget.

Name Description
accessKey

Specifies a shortcut key that sets focus on the widget element.

activeStateEnabled

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

allowItemDeleting

Specifies whether or not an end user can delete list items.

allowItemReordering

Specifies whether or not an end user can reorder list items.

bounceEnabled

A Boolean value specifying whether to enable or disable the bounce-back effect.

collapsibleGroups

Specifies whether or not an end-user can collapse groups.

dataSource

A data source used to fetch data to be displayed by the widget.

disabled

A Boolean value specifying whether or not the widget can respond to user interaction.

focusStateEnabled

Specifies whether or not the widget can be focused.

grouped

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

groupTemplate

The template to be used for rendering item groups.

height

Specifies the height of the widget.

hint

Specifies the text of the hint displayed for the widget.

hoverStateEnabled

A Boolean value specifying whether or not the widget changes its state when being hovered by an end user.

indicateLoading

Specifies whether or not to show the loading panel when the DataSource bound to the widget is loading data.

itemDeleteMode

Specifies the way a user can delete items from the list.

itemHoldTimeout

The time period in milliseconds before the onItemHold event is raised.

items

An array of items displayed by the widget.

itemTemplate

The template to be used for rendering items.

menuItems

Specifies the array of items for a context menu called for a list item.

menuMode

Specifies whether an item context menu is shown when a user holds or swipes an item.

nextButtonText

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

noDataText

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

onContentReady

A handler for the contentReady event.

onDisposing

A handler for the disposing event.

onGroupRendered

A handler for the groupRendered event.

onInitialized

A handler for the initialized event.

onItemClick

A handler for the itemClick event.

onItemContextMenu

A handler for the itemContextMenu event.

onItemDeleted

A handler for the itemDeleted event.

onItemDeleting

A handler for the itemDeleting event.

onItemHold

A handler for the itemHold event.

onItemRendered

A handler for the itemRendered event.

onItemReordered

A handler for the itemReordered event.

onItemSwipe

A handler for the itemSwipe event.

onOptionChanged

A handler for the optionChanged event.

onPageLoading

A handler for the pageLoading event.

onPullRefresh

A handler for the pullRefresh event.

onScroll

A handler for the scroll event.

onSelectAllValueChanged

A handler for the selectAllValueChanged event.

onSelectionChanged

A handler for the selectionChanged event.

pageLoadingText

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

pageLoadMode

Specifies whether the next page is loaded when a user scrolls the widget to the bottom or when the "next" button is clicked.

pulledDownText

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

pullingDownText

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

pullRefreshEnabled

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

refreshingText

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

rtlEnabled

Specifies whether or not the current component supports a right-to-left representation.

scrollByContent

A Boolean value specifying if the list is scrolled by content.

scrollByThumb

A Boolean value specifying if the list is scrolled using the scrollbar.

scrollingEnabled

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

selectedItems

An array of currently selected item objects.

selectionMode

Specifies item selection mode.

showScrollbar

Specifies when the widget shows the scrollbar.

showSelectionControls

Specifies whether or not to display controls used to select list items.

tabIndex

Specifies the widget tab index.

useNativeScrolling

Specifies whether or not the widget uses native scrolling.

visible

A Boolean value specifying whether or not the widget is visible.

width

Specifies the width of the widget.

Methods

This section describes members used to manipulate the widget.

Name Description
beginUpdate()

Prevents the component from refreshing until the endUpdate() method is called.

clientHeight()

Returns the height of the widget in pixels.

collapseGroup(groupIndex)

Collapses the specified group.

defaultOptions(rule)

Specifies the device-dependent default configuration options for this component.

deleteItem(itemElement)

Removes the specified item from the list.

deleteItem(itemIndex)

Removes the specified item from the list.

element()

Returns the root HTML element of the widget.

endUpdate()

Enables the component to refresh after the beginUpdate() method call.

expandGroup(groupIndex)

Expands the specified group.

focus()

Sets focus on the widget.

instance()

Returns an instance of this component class.

isItemSelected(itemElement)

Returns a Boolean value that indicates whether or not the specified item is selected.

isItemSelected(itemIndex)

Returns a Boolean value that indicates whether or not the specified item is selected.

off(eventName)

Detaches all event handlers from the specified event.

off(eventName, eventHandler)

Detaches a particular event handler from the specified event.

on(eventName, eventHandler)

Subscribes to a specified event.

on(events)

Subscribes to the specified events.

option()

Returns the configuration options of this component.

option(optionName)

Gets the value of the specified configuration option of this component.

option(optionName, optionValue)

Sets a value to the specified configuration option of this component.

option(options)

Sets one or more options of this component.

registerKeyHandler(key, handler)

Registers a handler when a specified key is pressed.

reload()

Reloads list data.

reorderItem(itemElement, toItemElement)

Moves the specified item to the specified position in the list.

reorderItem(itemIndex, toItemIndex)

Moves the specified item to the specified position in the list.

repaint()

Redraws the widget.

scrollBy(distance)

Scrolls the list content by the specified number of pixels.

scrollHeight()

Returns the height of the list content in pixels.

scrollTo(location)

Scrolls list content to the specified position.

scrollToItem(itemElement)

Scrolls the list to the specified item.

scrollToItem(itemIndex)

Scrolls the list to the specified item.

scrollTop()

Returns how far the list content is scrolled from the top.

selectItem(itemElement)

Selects the specified item.

selectItem(itemIndex)

Selects the specified item from the list.

unselectItem(itemElement)

Cancels the selection of the specified item.

unselectItem(itemIndex)

Unselects the specified item from the list.

updateDimensions()

Updates the widget scrollbar according to widget content size.

Events

This section describes events fired by this widget.

Name Description
contentReady

Fires when widget content is ready.

disposing

Fires when the widget is being removed.

groupRendered

Fires after an item group element is rendered.

initialized

Fires when the widget is initialized.

itemClick

Fires when a list item is clicked.

itemContextMenu

Fires when the right mouse button is clicked when the pointer is over a widget item, or when the "sustained" (also known as a long press) touch action is performed.

itemDeleted

Fires when a widget item is deleted.

itemDeleting

Fires before a collection item is deleted.

itemHold

Fires when the widget's collection item is being held for the time period specified by the itemHoldTimeout option.

itemRendered

Fires after a collection item is rendered.

itemReordered

Fires when a list item is moved to another position.

itemSwipe

Fires when an item is swiped.

optionChanged

Fires after an option of the component is changed.

pageLoading

Fires before loading the next page when autopaging is enabled.

pullRefresh

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

scroll

Fires on each scroll gesture.

selectAllValueChanged

Fires when the select all check box value changes.

selectionChanged

Fires after a collection item is selected or unselected.

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 the items of this widget. This template is based on certain fields of the data source provided for this widget. Below is a list of these fields. 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.

See Also