JavaScript/jQuery List - Getting Started

jQuery
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your application.
Angular
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your application.
Vue
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your application.
React
NOTE
Before you start the tutorial, ensure DevExtreme is installed in your application.

The List displays data from a local or remote data storage and allows users to group, select, search, reorder, and delete items.

This tutorial explains how to add a List to a page, bind it to data, and configure its core features. The following control demonstrates the result:

Each section in this tutorial covers a single configuration step. You can also find the full code in the following GitHub repository: Getting Started with List.

Create a List

jQuery

Add DevExtreme to your jQuery application and use the following code to create a List:

index.js
index.html
$(function () {
    $('#list').dxList({
        // Configuration goes here
    });
});
<html>
    <head>
        <!-- ... -->
        <script type="text/javascript" src="https://code.jquery.com/jquery-3.5.1.min.js"></script>

        <link rel="stylesheet" href="https://cdn3.devexpress.com/jslib/22.2.14/css/dx.light.css">
        <link rel="stylesheet" href="index.css">

        <script type="text/javascript" src="https://cdn3.devexpress.com/jslib/22.2.14/js/dx.all.js"></script>
        <script src="products.js"></script>
        <script type="text/javascript" src="index.js"></script>
    </head>
    <body class="dx-viewport">
        <div id="list"></div>
    </body>
</html>
Angular

Add DevExtreme to your Angular application and use the following code to create a List:

app.component.html
app.component.ts
app.module.ts
<dx-list id="list"
    <!-- Configuration goes here -->
>
</dx-list>
import { Component } from '@angular/core';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {

}
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

Add DevExtreme to your Vue application and use the following code to create a List:

App.vue
<template>
    <div id="app-container">
        <DxList id="list">
            <!-- Configuration goes here -->
        </DxList>
    </div>
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import { DxList } from 'devextreme-vue/list';

export default {
    components: {
        DxList
    }
}
</script>
React

Add DevExtreme to your React application and use the following code to create a List:

App.js
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import {
    List
} from 'devextreme-react/list';

function App() {
    return (
        <div className="App">
            <List id="list">
                {/* Configuration goes here */}
            </List>
        </div>
    );
}

export default App;

Bind the List to Data

The List can load data from different data source types. To use a local array, assign it to the dataSource property. If array elements are objects, use the displayExpr property to specify the data field that supplies values to the list. For information on other data source types, refer to the following articles:

jQuery
index.js
products.js
$(function () {
    $('#list').dxList({
        dataSource: products,
        displayExpr: 'Name',
    });
});
const products = [{
    ID: 1,
    Name: "HD Video Player",
    Category: "Video Players"
},
{
    ID: 3,
    Name: "SuperPlasma 50",
    Category: "Televisions"
},
{
    ID: 4,
    Name: "SuperLED 50",
    Category: "Televisions"
},
{
    ID: 5,
    Name: "SuperLED 42",
    Category: "Televisions"
},
{
    ID: 6,
    Name: "SuperLCD 55",
    Category: "Televisions"
},
{
    ID: 7,
    Name: "SuperLCD 42",
    Category: "Televisions"
},
{
    ID: 8,
    Name: "SuperPlasma 65",
    Category: "Televisions"
},
{
    ID: 9,
    Name: "SuperLCD 70",
    Category: "Televisions"
},
{
    ID: 10,
    Name: "DesktopLED 21",
    Category: "Monitors"
},
{
    ID: 12,
    Name: "DesktopLCD 21",
    Category: "Monitors"
},
{
    ID: 13,
    Name: "DesktopLCD 19",
    Category: "Monitors"
},
{
    ID: 14,
    Name: "Projector Plus",
    Category: "Projectors"
},
{
    ID: 15,
    Name: "Projector PlusHD",
    Category: "Projectors"
},
{
    ID: 17,
    Name: "ExcelRemote IR",
    Category: "Automation"
},
{
    ID: 18,
    Name: "ExcelRemote BT",
    Category: "Automation"
},
{
    ID: 19,
    Name: "ExcelRemote IP",
    Category: "Automation"
}];
Angular
app.component.html
app.component.ts
products.service.ts
<dx-list
    [dataSource]="products"
    displayExpr="Name">
</dx-list>
import { Component } from '@angular/core';
import { Product, ProductsService } from './products.service';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    products: Product[] = [];

    constructor(service: ProductsService) {
        this.products = service.getProducts();
    }
}
import { Injectable } from '@angular/core';

export interface Product {
    ID: Number,
    Name: String,
    Category: String,
}

const products: Product[] = [{
    ID: 1,
    Name: "HD Video Player",
    Category: "Video Players"
},
{
    ID: 3,
    Name: "SuperPlasma 50",
    Category: "Televisions"
},
{
    ID: 4,
    Name: "SuperLED 50",
    Category: "Televisions"
},
{
    ID: 5,
    Name: "SuperLED 42",
    Category: "Televisions"
},
{
    ID: 6,
    Name: "SuperLCD 55",
    Category: "Televisions"
},
{
    ID: 7,
    Name: "SuperLCD 42",
    Category: "Televisions"
},
{
    ID: 8,
    Name: "SuperPlasma 65",
    Category: "Televisions"
},
{
    ID: 9,
    Name: "SuperLCD 70",
    Category: "Televisions"
},
{
    ID: 10,
    Name: "DesktopLED 21",
    Category: "Monitors"
},
{
    ID: 12,
    Name: "DesktopLCD 21",
    Category: "Monitors"
},
{
    ID: 13,
    Name: "DesktopLCD 19",
    Category: "Monitors"
},
{
    ID: 14,
    Name: "Projector Plus",
    Category: "Projectors"
},
{
    ID: 15,
    Name: "Projector PlusHD",
    Category: "Projectors"
},
{
    ID: 17,
    Name: "ExcelRemote IR",
    Category: "Automation"
},
{
    ID: 18,
    Name: "ExcelRemote BT",
    Category: "Automation"
},
{
    ID: 19,
    Name: "ExcelRemote IP",
    Category: "Automation"
}];

@Injectable({
    providedIn: 'root'
})
export class ProductsService {
    getProducts(): Products[] {
        return products;
    }
}
Vue
App.vue
products.js
<template>
    <div id="app-container">
        <DxList
            :data-source="products"
            display-expr="Name">
        </DxList>
    </div>
</template>

<script>
// ...
import { products } from './products';

export default {
    // ...
    data() {
        return {
            products
        }
    },
}
</script>
export const products = [{
    ID: 1,
    Name: "HD Video Player",
    Category: "Video Players"
},
{
    ID: 3,
    Name: "SuperPlasma 50",
    Category: "Televisions"
},
{
    ID: 4,
    Name: "SuperLED 50",
    Category: "Televisions"
},
{
    ID: 5,
    Name: "SuperLED 42",
    Category: "Televisions"
},
{
    ID: 6,
    Name: "SuperLCD 55",
    Category: "Televisions"
},
{
    ID: 7,
    Name: "SuperLCD 42",
    Category: "Televisions"
},
{
    ID: 8,
    Name: "SuperPlasma 65",
    Category: "Televisions"
},
{
    ID: 9,
    Name: "SuperLCD 70",
    Category: "Televisions"
},
{
    ID: 10,
    Name: "DesktopLED 21",
    Category: "Monitors"
},
{
    ID: 12,
    Name: "DesktopLCD 21",
    Category: "Monitors"
},
{
    ID: 13,
    Name: "DesktopLCD 19",
    Category: "Monitors"
},
{
    ID: 14,
    Name: "Projector Plus",
    Category: "Projectors"
},
{
    ID: 15,
    Name: "Projector PlusHD",
    Category: "Projectors"
},
{
    ID: 17,
    Name: "ExcelRemote IR",
    Category: "Automation"
},
{
    ID: 18,
    Name: "ExcelRemote BT",
    Category: "Automation"
},
{
    ID: 19,
    Name: "ExcelRemote IP",
    Category: "Automation"
}];
React
App.js
products.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

import {
    List
} from 'devextreme-react/list';
import { products } from './products';

function App() {
    return (
        <div className="App">
            <List
                dataSource={products}
                displayExpr="Name">
            </List>
        </div>
    );
}

export default App;
export const products = [{
    ID: 1,
    Name: "HD Video Player",
    Category: "Video Players"
},
{
    ID: 3,
    Name: "SuperPlasma 50",
    Category: "Televisions"
},
{
    ID: 4,
    Name: "SuperLED 50",
    Category: "Televisions"
},
{
    ID: 5,
    Name: "SuperLED 42",
    Category: "Televisions"
},
{
    ID: 6,
    Name: "SuperLCD 55",
    Category: "Televisions"
},
{
    ID: 7,
    Name: "SuperLCD 42",
    Category: "Televisions"
},
{
    ID: 8,
    Name: "SuperPlasma 65",
    Category: "Televisions"
},
{
    ID: 9,
    Name: "SuperLCD 70",
    Category: "Televisions"
},
{
    ID: 10,
    Name: "DesktopLED 21",
    Category: "Monitors"
},
{
    ID: 12,
    Name: "DesktopLCD 21",
    Category: "Monitors"
},
{
    ID: 13,
    Name: "DesktopLCD 19",
    Category: "Monitors"
},
{
    ID: 14,
    Name: "Projector Plus",
    Category: "Projectors"
},
{
    ID: 15,
    Name: "Projector PlusHD",
    Category: "Projectors"
},
{
    ID: 17,
    Name: "ExcelRemote IR",
    Category: "Automation"
},
{
    ID: 18,
    Name: "ExcelRemote BT",
    Category: "Automation"
},
{
    ID: 19,
    Name: "ExcelRemote IP",
    Category: "Automation"
}];

Select Items

The List supports "single", "multiple", and "all" item selection modes. To enable selection, assign one of these modes to the selectionMode property.

jQuery
index.js
$(function () {
    $('#list').dxList({
        // ...
        selectionMode: 'single',
     });
});
Angular
app.component.html
<dx-list...
    selectionMode="single">
</dx-list>
Vue
App.vue
<template>
    <div id="app-container">
        <DxList...
            selection-mode="single">
        </DxList>
    </div>
</template>

<script>
// ...
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

function App() {
    return (
        <div className="App">
            <List...
                selectionMode="single">
            </List>
        </div>
    );
}

export default App;

View Demo

Group Items

The List can display items as a two-level hierarchy: parent and child items. To group items, set the grouped property to true and ensure that data is structured as a hierarchical array of objects. The control recognizes a hierarchy if objects contain properties named key and nested lists named items. Refer to the following help topic for more information and additional ways to build a hierarchy: Grouping in the Data Source.

You can also display a hierarchy in a list bound to a flat array. In this case, use the DataSource component. Wrap your array in a store as shown below. Assign the grouping field to the DataSource's group property.

jQuery
index.js
$(function () {
    $('#list').dxList({
        dataSource: new DevExpress.data.DataSource({
            store: products,
            group: 'Category',
        }),
        grouped: true,
    });    
});
Angular
app.component.html
app.component.ts
<dx-list...
    [dataSource]="dataSource"
    [grouped]="true">
</dx-list>
import { Component } from '@angular/core';
import DataSource from "devextreme/data/data_source";
import { Product, ProductsService } from './products.service';

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css']
})
export class AppComponent {
    dataSource: DataSource;
    products: Product[] = [];

    constructor(service: ProductsService) {
        this.products = service.getProducts();
        this.dataSource = new DataSource({
            store: this.products,
            group: "Category"
        });
    }
}
Vue
App.vue
<template>
    <div id="app-container">
        <DxList...
            :data-source="dataSource"
            :grouped="true">
        </DxList>
    </div>
</template>

<script>
// ...
import { products } from './products';
import DataSource from "devextreme/data/data_source";

export default {
    // ...
    data() {
        return {
            dataSource: new DataSource({
                store: products,
                group: "Category"
            }),
        }
    },
}
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

// ...    
import { products } from './products';
import DataSource from "devextreme/data/data_source";

const dataSource = new DataSource({
    store: products,
    group: "Category"
});

function App() {
    return (
        <div className="App">
            <List...
                dataSource={dataSource}
                grouped={true}>
            </List>
        </div>
    );
}

export default App;

View Demo

Search Items

To add a search bar to the List, set the searchEnabled property to true. Use the searchMode property to specify whether found list items should start with, contain, or match the search string.

jQuery
index.js
$(function () {
    $('#list').dxList({
        // ...
        searchEnabled: true,
        searchMode: 'contains',
    });
});
Angular
app.component.html
<dx-list...
    [searchEnabled]="true"
    searchMode="contains">
</dx-list>
Vue
App.vue
<template>
    <div id="app-container">
        <DxList...
            :search-enabled="true"
            search-mode="contains">
        </DxList>
    </div>
</template>

<script>
// ...
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

function App() {
    return (
        <div className="App">
            <List...
                searchEnabled={true}
                searchMode="contains">
            </List>
        </div>
    );
}

export default App;

View Demo

Reorder Items

Users can drag and drop list items to reorder them. To configure this functionality, define the itemDragging object. Within this object, set the allowReordering property to true.

jQuery
index.js
$(function () {
    $('#list').dxList({
        // ...
        itemDragging: {
            allowReordering: true,
        },
    });
});
Angular
app.component.html
<dx-list...>
    <dxo-item-dragging 
        [allowReordering]="true">
    </dxo-item-dragging>
</dx-list>
Vue
App.vue
<template>
    <div id="app-container">
        <DxList...>
            <DxItemDragging
                :allow-reordering="true"
             />
        </DxList>
    </div>
</template>

<script>
// ...
import DxList, { DxItemDragging } from "devextreme-vue/list";

export default {
    components: {
        // ...
        DxItemDragging
    },
    // ...
}
</script>
React
App.js
//...
import List, { ItemDragging } from "devextreme-react/list";

function App() {
    return (
        <div className="App">
            <List...>
                <ItemDragging 
                    allowReordering={true} 
                />
            </List>
        </div>
    );
}

export default App;

View Demo

Delete Items

To allow users to delete items from the List, set the allowItemDeleting property to true. Use the itemDeleteMode property to select the UI elements and/or user actions that remove items.

jQuery
index.js
$(function () {
    $('#list').dxList({
        // ...
        allowItemDeleting: true,
    });
});
Angular
app.component.html
<dx-list...
    [allowItemDeleting]="true">
</dx-list>
Vue
App.vue
<template>
    <div id="app-container">
        <DxList...
            :allow-item-deleting="true">
        </DxList>
    </div>
</template>

<script>
// ...
</script>
React
App.js
import React from 'react';

import 'devextreme/dist/css/dx.light.css';

function App() {
    return (
        <div className="App">
            <List...
                allowItemDeleting={true}>
            </List>
        </div>
    );
}

export default App;

View Demo