React List - Selection

User Interaction

In the List UI component, selection is disabled by default. To enable it, choose one of selection modes using the selectionMode property.

jQuery
JavaScript
$(function() {
    $("#listContainer").dxList({
        // ...
        selectionMode: "single" // or "multiple" | "all" | "none" (disables selection)
    });
});
Angular
HTML
TypeScript
<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 property 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
JavaScript
$(function() {
    $("#listContainer").dxList({
        // ...
        showSelectionControls: true
    });
});
Angular
HTML
TypeScript
<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 property.

jQuery
JavaScript
$(function() {
    $("#listContainer").dxList({
        // ...
        selectAllMode: "allPages" // or "page"
    });
});
Angular
HTML
TypeScript
<dx-list ...
    selectAllMode="allPages"> <!-- or "page" -->
</dx-list>
import { DxListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxListModule
    ],
    // ...
})

View Demo

See Also

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
    JavaScript
    const list = $("#listContainer").dxList("instance");
let 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
    TypeScript
    import { ..., 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
    HTML
    TypeScript
    <dx-list ...
    [selectedItemKeys]="[0, 2, 5]">
</dx-list>
    import { DxListModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxListModule
    ],
    // ...
})
    NOTE
    To specify the key field, use the keyExpr property of the List or the key property of the Store.

  • By data object
    Add or remove the data object from the selectedItems collection.

    jQuery
    JavaScript
    const fruits = [
    { fruit: "Apples", count: 10 },
    { fruit: "Oranges", count: 12 },
    { fruit: "Lemons", count: 15 }
];
const list = $("#listContainer").dxList("instance");
let 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
    TypeScript
    import { ..., 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
    JavaScript
    const fruits = [
    // ...
];
$(function() {
    $("#listContainer").dxList({
        dataSource: fruits,
        selectedItems: [fruits[0], fruits[2]]
    });
});
    Angular
    HTML
    TypeScript
    <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
    JavaScript
    const 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
const itemToUnselect = { group: 2, item: 3 };
if(list.isItemSelected(itemToUnselect)) {
    list.unselectItem(itemToUnselect);
}
    Angular
    TypeScript
    import { ..., 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
    JavaScript
    const list = $("#listContainer").dxList("instance");
const 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
    TypeScript
    import { ..., 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 () {
        const itemNodes = document.getElementsByClassName("dx-list-item");
        // Selects the last item by its DOM node
        this.list.instance.selectItem(itemNodes[itemNodes.length-1]);
    }
    unselectLastItem () {
        const 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

Events

The List UI component fires the selectionChanged event when an item is selected or when the selection is cancelled. The UI component 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 UI component, assign them to the corresponding onEventName properties when you configure the UI component.

jQuery
JavaScript
$(function () {
    $("#listContainer").dxList({
        // ...
        onSelectionChanged: function(e) {
            const addedItems = e.addedItems;
            const removedItems = e.removedItems;
            // Handler of the "selectionChanged" event
        },
        onSelectAllValueChanged: function(e) {
            const newCheckBoxValue = e.value;
            // Handler of the "selectAllValueChanged" event
        }
    });
});
Angular
HTML
TypeScript
<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
    ],
    // ...
})

View Demo

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.

JavaScript
const selectionChangedEventHandler1 = function(e) {
    // First handler of the "selectionChanged" event
};

const selectionChangedEventHandler2 = function(e) {
    // Second handler of the "selectionChanged" event
};

$("#listContainer").dxList("instance")
    .on("selectionChanged", selectionChangedEventHandler1)
    .on("selectionChanged", selectionChangedEventHandler2);
See Also