User Interaction
To enable selection in the List component, use the selectionMode property to specify the selection mode.
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
],
// ...
})Vue
<template>
<DxList ...
selection-mode="single" /> <!-- or "multiple" | "all" | "none" (disables selection) -->
</template>
<script>
import 'devextreme/dist/css/dx.light.css';
import DxList from 'devextreme-vue/list';
export default {
components: {
DxList
},
// ...
}
</script>React
import React from 'react';
import 'devextreme/dist/css/dx.light.css';
import List from 'devextreme-react/list';
export default function App() {
return (
<List ...
selectionMode="single" /> {/* or "multiple" | "all" | "none" (disables selection) */}
);
}To select a List item, a user should click or tap it. Selected items become shaded. If you want to indicate selected items, set the showSelectionControls property to true. This setting adds a checkbox to each item on the List. Enable this option if you use the "all" selection mode. Otherwise, the "Select All" checkbox is not shown.
If you want users to select List items only by checking checkboxes, assign false to the selectByClick property.
jQuery
$(function() {
$("#listContainer").dxList({
// ...
showSelectionControls: true
});
});Angular
<dx-list ...
[showSelectionControls]="true">
</dx-list>
import { DxListModule } from "devextreme-angular";
// ...
export class AppComponent {
// ...
}
@NgModule({
imports: [
// ...
DxListModule
],
// ...
})Vue
<template>
<DxList ...
:show-selection-controls="true"
/>
</template>
<script>
import 'devextreme/dist/css/dx.light.css';
import DxList from 'devextreme-vue/list';
export default {
components: {
DxList
},
// ...
}
</script>React
import React from 'react';
import 'devextreme/dist/css/dx.light.css';
import List from 'devextreme-react/list';
export default function App() {
return (
<List ...
showSelectionControls={true}
/>
);
}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
$(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
],
// ...
})Vue
<template>
<DxList ...
select-all-mode="allPages" /> <!-- or "page" -->
</template>
<script>
import 'devextreme/dist/css/dx.light.css';
import DxList from 'devextreme-vue/list';
export default {
components: {
DxList
},
// ...
}
</script>React
import React from 'react';
import 'devextreme/dist/css/dx.light.css';
import List from 'devextreme-react/list';
export default function App() {
return (
<List ...
selectAllMode="allPages" /> {/* or "page" */}
);
}See Also
jQuery
Angular
Vue
React
API
To configure the initial selection or access the keys of selected items, use the selectedItemKeys collection. Add or remove an item's key from this collection to select the item or cancel its selection:
jQuery
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
<dx-list ...
[(selectedItemKeys)]="selectedKeys">
</dx-list>
import { Component } from '@angular/core';
@Component({
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: ['./app.component.css']
})
export class AppComponent {
selectedKeys: Array<number> = [6, 2, 5];
selectItem(key) {
if(!this.selectedKeys.includes(key)) {
this.selectedKeys.push(key);
}
}
deselectItem(key) {
this.selectedKeys = this.selectedKeys.filter((data) => {
return data !== key;
});
}
}
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { AppComponent } from './app.component';
import { DxListModule } from 'devextreme-angular';
@NgModule({
declarations: [
AppComponent
],
imports: [
BrowserModule,
DxListModule
],
providers: [ ],
bootstrap: [AppComponent]
})
export class AppModule { }Vue
<template>
<DxList ...
v-model:selected-item-keys="selectedKeys"
/>
</template>
<script>
import 'devextreme/dist/css/dx.light.css';
import DxList from 'devextreme-vue/list';
export default {
components: {
DxList
},
data() {
return {
selectedKeys: [6, 2, 5]
}
},
methods: {
selectItem(key) {
if(!this.selectedKeys.includes(key)) {
this.selectedKeys = [...this.selectedKeys, key];
}
},
deselectItem(key) {
this.selectedKeys = this.selectedKeys.filter((data) => {
return data !== key;
});
}
}
}
</script>React
import React, { useState } from 'react';
import 'devextreme/dist/css/dx.light.css';
import List from 'devextreme-react/list';
export default function App() {
const [selectedKeys, setSelectedKeys] = useState([6, 2, 5]);
const selectItem = (key) => {
if (!selectedKeys.includes(key)) {
const newSelectedKeys = [...selectedKeys, key];
setSelectedKeys(newSelectedKeys);
}
};
const deselectItem = (key) => {
const filteredSelectedKeys = selectedKeys.filter((data) => {
return data !== key;
});
setSelectedKeys(filteredSelectedKeys);
};
const handleSelectionChange = (e) => {
if (e.name === "selectedItemKeys") {
setSelectedKeys(e.value);
}
};
return (
<List ...
selectedItemKeys={selectedKeys}
onOptionChanged={handleSelectionChange}
/>
);
}You can also call the selectItem method to select a List item by index. To unselect an item, call unselectItem.
Implement the onSelectionChanged event handler to perform an action after a user selects items. To cancel selection programmatically, use onSelectionChanging. To see an example, refer to the following demo: List Selection.
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
$(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
<dx-list ...
(onSelectionChanged)="onSelectionChanged($event)"
(onSelectAllValueChanged)="onSelectAllValueChanged($event)">
</dx-list>
import { DxListModule } from "devextreme-angular";
// ...
export class AppComponent {
onSelectionChanged (e) {
const addedItems = e.addedItems;
const removedItems = e.removedItems;
// Handler of the "selectionChanged" event
}
onSelectAllValueChanged (e) {
const newCheckBoxValue = e.value;
// Handler of the "selectAllValueChanged" event
}
}
@NgModule({
imports: [
// ...
DxListModule
],
// ...
})Vue
<template>
<DxList ...
@selection-changed="onSelectionChanged"
@select-all-value-changed="onSelectAllValueChanged"
/>
</template>
<script>
import 'devextreme/dist/css/dx.light.css';
import DxList from 'devextreme-vue/list';
export default {
components: {
DxList
},
// ...
methods: {
onSelectionChanged (e) {
const addedItems = e.addedItems;
const removedItems = e.removedItems;
// Handler of the "selectionChanged" event
},
onSelectAllValueChanged (e) {
const newCheckBoxValue = e.value;
// Handler of the "selectAllValueChanged" event
}
}
}
</script>React
import React from 'react';
import 'devextreme/dist/css/dx.light.css';
import List from 'devextreme-react/list';
const onSelectionChanged = (e) => {
const addedItems = e.addedItems;
const removedItems = e.removedItems;
// Handler of the "selectionChanged" event
};
const onSelectAllValueChanged = (e) => {
const newCheckBoxValue = e.value;
// Handler of the "selectAllValueChanged" event
}
export default function App() {
return (
<List ...
onSelectionChanged={onSelectionChanged}
onSelectAllValueChanged={onSelectAllValueChanged}
/>
);
}jQuery
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.
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);