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
],
// ...
})Vue
App.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
App.js
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, 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
],
// ...
})Vue
App.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
App.js
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
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
],
// ...
})Vue
App.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
App.js
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
API
Add or remove an item's key from the selectedItemKeys collection to select the item or cancel its selection:
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
app.component.html
app.component.ts
app.module.ts
<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
App.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
App.js
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}
/>
);
}NOTE
See Also
- Call Methods: Angular | Vue | React | jQuery | AngularJS | Knockout
- List Demos
- List API Reference
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) {
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
App.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
App.js
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}
/>
);
}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
Feedback