User Interaction
In the List widget, selection is disabled by default. To enable it, choose one of selection modes using the selectionMode option.
jQuery
$(function() { $("#listContainer").dxList({ // ... selectionMode: "single" // or "multiple" | "all" | "none" (disables selection) }); });
Angular
<dx-list ... selectionMode="single"> <!-- or "multiple" | "all" | "none" (disables selection) --> </dx-list>
import { DxListModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxListModule ], // ... })
To select a List item, an end user simply clicks or taps it. Selected items become shaded. If you want to indicate selected items more manifestly, set the showSelectionControls option to true. This setting adds a check box to each item on the List. Also, make this setting if you use the "all" selectionMode. Otherwise, the "Select All" check box will be missing.
jQuery
$(function() { $("#listContainer").dxList({ // ... showSelectionControls: true }); });
Angular
<dx-list ... [showSelectionControls]="true"> </dx-list>
import { DxListModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxListModule ], // ... })
When data in the List is paginated, you can choose whether the "Select All" check box will select all items on all pages or items on the currently rendered pages only. To make this choice, specify the selectAllMode option.
jQuery
$(function() { $("#listContainer").dxList({ // ... selectAllMode: "allPages" // or "page" }); });
Angular
<dx-list ... selectAllMode="allPages"> <!-- or "page" --> </dx-list>
import { DxListModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxListModule ], // ... })
See Also
- Configure a Widget: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
- List - Localization
API
You can select an item or cancel its selection in the following ways.
By key
Add or remove the key from the selectedItemKeys collection.jQuery
JavaScriptvar list = $("#listContainer").dxList("instance"); var selectedKeys = list.option("selectedItemKeys"); // Selects the item with key 5 selectedKeys.push(5); list.option("selectedItemKeys", selectedKeys); // Cancels the selection of the item with key 5 selectedKeys = $.grep(selectedKeys, function(key) { return key != 5; }); list.option("selectedItemKeys", selectedKeys);
Angular
TypeScriptimport { ..., ViewChild } from "@angular/core"; import { DxListModule, DxListComponent } from "devextreme-angular"; // ... export class AppComponent { @ViewChild(DxListComponent, { static: false }) list: DxListComponent; // Prior to Angular 8 // @ViewChild(DxListComponent) list: DxListComponent; selectItem (key) { let selectedKeys = this.list.instance.option("selectedItemKeys"); if(selectedKeys.includes(key)) { // Cancels the selection of the item with the key selectedKeys = selectedKeys.filter((data) => { return data != key; }); } else { // Selects the item with the key selectedKeys.push(key); } this.list.instance.option("selectedItemKeys", selectedKeys); } } @NgModule({ imports: [ // ... DxListModule ], // ... })
You can also use the selectedItemKeys collection to select items initially.
jQuery
JavaScript$(function() { $("#listContainer").dxList({ // ... selectedItemKeys: [0, 2, 5] }); });
Angular
HTMLTypeScript<dx-list ... [selectedItemKeys]="[0, 2, 5]"> </dx-list>
import { DxListModule } from "devextreme-angular"; // ... export class AppComponent { // ... } @NgModule({ imports: [ // ... DxListModule ], // ... })
By data object
Add or remove the data object from the selectedItems collection.jQuery
JavaScriptvar fruits = [ { fruit: "Apples", count: 10 }, { fruit: "Oranges", count: 12 }, { fruit: "Lemons", count: 15 } ]; var list = $("#listContainer").dxList("instance"); var selectedItems = list.option("selectedItems"); // Selects the "Oranges" item selectedItems.push(fruits[1]); list.option("selectedItems", selectedItems); // Cancels the selection of the "Oranges" item selectedItems = $.grep(selectedItems, function(item) { return item != fruits[1]; }); list.option("selectedItems", selectedItems);
Angular
TypeScriptimport { ..., ViewChild } from "@angular/core"; import { DxListModule, DxListComponent } from "devextreme-angular"; // ... export class AppComponent { @ViewChild(DxListComponent, { static: false }) list: DxListComponent; // Prior to Angular 8 // @ViewChild(DxListComponent) list: DxListComponent; fruits = [ { fruit: "Apples", count: 10 }, { fruit: "Oranges", count: 12 }, { fruit: "Lemons", count: 15 } ]; selectOranges () { let selectedItems = this.list.instance.option("selectedItems"); selectedItems.push(fruits[1]); this.list.instance.option("selectedItems", selectedItems); } unselectOranges () { let selectedItems = this.list.instance.option("selectedItems"); selectedItems = selectedItems.filter((item) => { return item != fruits[1]; }); this.list.instance.option("selectedItems", selectedItems); } } @NgModule({ imports: [ // ... DxListModule ], // ... })
You can also use the selectedItems collection to select items initially.
jQuery
JavaScriptvar fruits = [ // ... ]; $(function() { $("#listContainer").dxList({ dataSource: fruits, selectedItems: [fruits[0], fruits[2]] }); });
Angular
HTMLTypeScript<dx-list ... [dataSource]="fruits" [selectedItems]="[fruits[0], fruits[2]]"> </dx-list>
import { DxListModule } from "devextreme-angular"; // ... export class AppComponent { fruits = [ // ... ] } @NgModule({ imports: [ // ... DxListModule ], // ... })
By index
Pass the index to the selectItem(itemIndex) or unselectItem(itemIndex) method. If the List is grouped, these methods should be given an object with the indexes of the group and the item.jQuery
JavaScriptvar list = $("#listContainer").dxList("instance"); // Selects the item with index 1 list.selectItem(1); // Checks that the item with index 1 is selected; if so, cancels the selection if(list.isItemSelected(1)) { list.unselectItem(1); } // Selects the item with index 3 in the group with index 2 list.selectItem({ group: 2, item: 3 }); // Checks that the item with index 3 in the group with index 2 is selected; if so, cancels the selection var itemToUnselect = { group: 2, item: 3 }; if(list.isItemSelected(itemToUnselect)) { list.unselectItem(itemToUnselect); }
Angular
TypeScriptimport { ..., ViewChild } from "@angular/core"; import { DxListModule, DxListComponent } from "devextreme-angular"; // ... export class AppComponent { @ViewChild(DxListComponent, { static: false }) list: DxListComponent; // Prior to Angular 8 // @ViewChild(DxListComponent) list: DxListComponent; selectItem (index) { // Checks that the item with the index is selected if (this.list.isItemSelected(index)) { // If the item is selected, clears its selection this.list.instance.unselectItem(index); } else { // If the item is not selected, selects it this.list.instance.selectItem(index); } } selectItemInGroup (groupIndex, itemIndex) { let item = { group: groupIndex, item: itemIndex }; // Checks that the item is selected if(this.list.instance.isItemSelected(item)) { // If the item is selected, clears its selection this.list.instance.unselectItem(item); } else { // If the item is not selected, selects it this.list.instance.selectItem(item); } } } @NgModule({ imports: [ // ... DxListModule ], // ... })
By DOM node
Pass the DOM node to the selectItem(itemElement) or unselectItem(itemElement) method.jQuery
JavaScriptvar list = $("#listContainer").dxList("instance"); var itemNodes = $("#listContainer").find(".dx-list-item"); // Selects the last item by its DOM node list.selectItem(itemNodes[itemNodes.length-1]); // Checks that the last item is selected; if so, cancels the selection if(list.isItemSelected(itemNodes[itemNodes.length-1])) { list.unselectItem(itemNodes[itemNodes.length-1]); }
Angular
TypeScriptimport { ..., ViewChild } from "@angular/core"; import { DxListModule, DxListComponent } from "devextreme-angular"; // ... export class AppComponent { @ViewChild(DxListComponent, { static: false }) list: DxListComponent; // Prior to Angular 8 // @ViewChild(DxListComponent) list: DxListComponent; selectLastItem () { var itemNodes = document.getElementsByClassName("dx-list-item"); // Selects the last item by its DOM node this.list.instance.selectItem(itemNodes[itemNodes.length-1]); } unselectLastItem () { var itemNodes = document.getElementsByClassName("dx-list-item"); // Checks that the last item is selected; if so, cancels the selection if(this.list.instance.isItemSelected(itemNodes[itemNodes.length-1])) { this.list.instance.unselectItem(itemNodes[itemNodes.length-1]); } } } @NgModule({ imports: [ // ... DxListModule ], // ... })
See Also
- Call Methods: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
- List Demos
- List API Reference
Events
The List widget fires the selectionChanged event when an item is selected or when the selection is cancelled. The widget also fires the selectAllValueChanged event when the "Select All" check box has changed its value. If the functions that handle these events are not going to be changed during the lifetime of the widget, assign them to the corresponding onEventName options when you configure the widget.
jQuery
$(function () { $("#listContainer").dxList({ // ... onSelectionChanged: function(e) { var addedItems = e.addedItems; var removedItems = e.removedItems; // Handler of the "selectionChanged" event }, onSelectAllValueChanged: function(e) { var newCheckBoxValue = e.value; // Handler of the "selectAllValueChanged" event } }); });
Angular
<dx-list ... (onSelectionChanged)="onSelectionChanged($event)" (onSelectAllValueChanged)="onSelectAllValueChanged($event)"> </dx-list>
import { DxListModule } from "devextreme-angular"; // ... export class AppComponent { onSelectionChanged (e) { let addedItems = e.addedItems; let removedItems = e.removedItems; // Handler of the "selectionChanged" event } onSelectAllValueChanged (e) { let newCheckBoxValue = e.value; // Handler of the "selectAllValueChanged" event } } @NgModule({ imports: [ // ... DxListModule ], // ... })
If you are going to change the event handlers at runtime, or if you need to attach several handlers to a single event, subscribe to this event using the on(eventName, eventHandler) method. This approach is more typical of jQuery.
var selectionChangedEventHandler1 = function(e) { // First handler of the "selectionChanged" event }; var selectionChangedEventHandler2 = function(e) { // Second handler of the "selectionChanged" event }; $("#listContainer").dxList("instance") .on("selectionChanged", selectionChangedEventHandler1) .on("selectionChanged", selectionChangedEventHandler2);
See Also
- Handle Events: Angular | Vue | React | jQuery | AngularJS | Knockout | ASP.NET MVC 5 | ASP.NET Core
- List API Reference
If you have technical questions, please create a support ticket in the DevExpress Support Center.