JavaScript/jQuery List Options

View on GitHub

See Also

The value of this property will be passed to the accesskey attribute of the HTML element that underlies the UI component.

The UI component switches to the active state when users press down the primary mouse button. When this property is set to true, the CSS rules for the active state apply. You can change these rules to customize the component.

Use this property when you display the component on a platform whose guidelines include the active state change for UI components.

View Demo

See Also

• List - Item Deletion - User Interaction

If the property is set to true, you can scroll the list content up (down) even if you have reached the bottom (top) boundary. But when you release the content, it returns to the bound position. If the property value is false, you can scroll the list content until you reach the boundary.

See Also

• List - Scrolling - User Interaction

This property makes sense if the grouped property is set to true.

If the collapsibleGroups property is set to true, the down arrow is displayed to the right of a group header. An end user can collapse or expand a group simply clicking the group header.

View Demo

See Also

• List - Expand and Collapse a Group

View Demo

The List works with collections of string values or objects.

Depending on your data source, bind List to data as follows. If the data source provides objects, also specify the itemTemplate. You can skip this part if the objects contain fields described in the items section.

• Data Array
  Assign the array to the dataSource option. View Demo

• Read-Only Data in JSON Format
  Set the dataSource property to the URL of a JSON file or service that returns JSON data.

• OData
  Implement an ODataStore.

• Web API, PHP, MongoDB
  Use one of the following extensions to enable the server to process data according to the protocol DevExtreme UI components use:

  • DevExtreme.AspNet.Data
  • DevExtreme-PHP-Data
  • devextreme-query-mongodb

  Then, use the createStore method to configure access to the server on the client as shown below. This method is part of DevExtreme.AspNet.Data.

  jQuery

  JavaScript

  $(function() {
      let serviceUrl = "https://url/to/my/service";
      $("#listContainer").dxList({
          // ...
          dataSource: DevExpress.data.AspNet.createStore({
              key: "ID",
              loadUrl: serviceUrl + "/GetAction",
              insertUrl: serviceUrl + "/InsertAction",
              updateUrl: serviceUrl + "/UpdateAction",
              deleteUrl: serviceUrl + "/DeleteAction"
          })
      })
  });

  Angular

  app.component.ts

  app.component.html

  app.module.ts

  import { Component } from '@angular/core';
  import CustomStore from 'devextreme/data/custom_store';
  import { createStore } from 'devextreme-aspnet-data-nojquery';
  
  @Component({
      selector: 'app-root',
      templateUrl: './app.component.html',
      styleUrls: ['./app.component.css']
  })
  export class AppComponent {
      store: CustomStore;
      constructor() {
          let serviceUrl = "https://url/to/my/service";
          this.store = createStore({
              key: "ID",
              loadUrl: serviceUrl + "/GetAction",
              insertUrl: serviceUrl + "/InsertAction",
              updateUrl: serviceUrl + "/UpdateAction",
              deleteUrl: serviceUrl + "/DeleteAction"
          })
      }
  }

  <dx-list ...
      [dataSource]="store">
  </dx-list>

  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 ...
          :data-source="store" />
  </template>
  
  <script>
  import 'devextreme/dist/css/dx.light.css';
  
  import CustomStore from 'devextreme/data/custom_store';
  import { createStore } from 'devextreme-aspnet-data-nojquery';
  import { DxList } from 'devextreme-vue/list';
  
  export default {
      components: {
          DxList
      },
      data() {
          const serviceUrl = "https://url/to/my/service";
          const store = createStore({
              key: "ID",
              loadUrl: serviceUrl + "/GetAction",
              insertUrl: serviceUrl + "/InsertAction",
              updateUrl: serviceUrl + "/UpdateAction",
              deleteUrl: serviceUrl + "/DeleteAction"
          });
          return {
              store
          }
      }
  }
  </script>

  React

  App.js

  import React from 'react';
  import 'devextreme/dist/css/dx.light.css';
  
  import CustomStore from 'devextreme/data/custom_store';
  import { createStore } from 'devextreme-aspnet-data-nojquery';
  import List from 'devextreme-react/list';
  
  const serviceUrl = "https://url/to/my/service";
  const store = createStore({
      key: "ID",
      loadUrl: serviceUrl + "/GetAction",
      insertUrl: serviceUrl + "/InsertAction",
      updateUrl: serviceUrl + "/UpdateAction",
      deleteUrl: serviceUrl + "/DeleteAction"
  });
  
  class App extends React.Component {
      render() {
          return (
              <List ...
                  dataSource={store} />
          );
      }
  }
  export default App;

  View Demo

• Any other data source
  Implement a CustomStore.

Regardless of the data source on the input, the List always wraps it in the DataSource object. This object allows you to sort, filter, group, and perform other data shaping operations. To get its instance, call the getDataSource() method.

Set this property to the name of a data field that provides displayed values...

displayExpr: "name"

... or to a function that returns the displayed value:

displayExpr: function(item) {
    // "item" can be null
    return item && 'ID: ' + item.id + ', Name: ' + item.name;
}

Leave this property unspecified or set it to this if the data source contains primitives.

When this property is true, make sure that all data source objects have the following structure:

const dataSource = [{
    key: "Group 1", // Group caption 
    items: [ // Items in the group
        { ... },
        { ... }
    ]
}, {
    // ...
}];

View Demo

You can supply data to this structure using the DataSource object's group property.

See Also

• List - Grouping

View Demo

See Also

• Customize Group Headers
• Custom Templates

This property accepts a value of one of the following types:

• Number
  The height in pixels.

• String
  A CSS-accepted measurement of height. For example, "55px", "20vh", "80%", "inherit".

• Function (deprecated since v21.2)
  Refer to the W0017 warning description for information on how you can migrate to viewport units.

View Demo

See Also

• List - Item Deletion - User Interaction

See the Sortable configuration for properties that you can specify in this object.

View Demo

The items array can contain:

• Strings
• Objects with fields described in this section
• Objects with any other fields. In this case, specify the itemTemplate.

If you need to update the UI component items, reassign the entire items array as shown in the following example:

listInstance.option('items', newItems);

As an alternative to items, you can use the dataSource property. It accepts the DataSource object, whose underlying stores provide an API that allows you to update individual items without reassigning the entire item collection.

View Demo

View Demo

See Also

• Customize Item Appearance
• Custom Templates

View Demo

See Also

• Specify data using dataSource property
• Specify data using items property

See Also

• List - Item Context Menu

See Also

• List - Item Context Menu

See Also

• List - Localization

The List component evaluates the noDataText property's value. This evaluation, however, makes the List potentially vulnerable to XSS attacks. To guard against these attacks, encode the HTML markup before you assign it to the noDataText property. Refer to the following help topic for more information: Potentially Vulnerable API - noDataText.

See Also

• grouped

<dx-list ...
    (onInitialized)="saveInstance($event)">
</dx-list>

import { Component } from "@angular/core";
import List from "devextreme/ui/data_grid";
// ...
export class AppComponent {
    listInstance: List;
    saveInstance (e) {
        this.listInstance = e.component;
    }
}

<template>
    <div>
        <DxList ...
            @initialized="saveInstance">
        </DxList>
    </div>
</template>

<script>
import DxList from 'devextreme-vue/list';

export default {
    components: {
        DxList
    },
    data: function() {
        return {
            listInstance: null
        };
    },
    methods: {
        saveInstance: function(e) {
            this.listInstance = e.component;
        }
    }
};
</script>

<template>
    <div>
        <DxList ...
            @initialized="saveInstance">
        </DxList>
    </div>
</template>

<script setup>
import DxList from 'devextreme-vue/list';

let listInstance = null;

const saveInstance = (e) => {
    listInstance = e.component;
}
</script>

import List from 'devextreme-react/list';

class App extends React.Component {
    constructor(props) {
        super(props);

        this.saveInstance = this.saveInstance.bind(this);
    }

    saveInstance(e) {
        this.listInstance = e.component;
    }

    render() {
        return (
            <div>
                <List onInitialized={this.saveInstance} />
            </div>
        );
    }
}

See Also

Note that the itemDeleted event is raised only if an item is deleted using the appropriate method of the UI component or end-user interaction. If you delete an item from an observable array passed to the dataSource or items property, the UI component entirely reloads the items array without raising the itemDeleted and itemDeleting events.

View Demo

See Also

• List - Handle Deletion-Related Events

You can cancel item deletion by setting the handler parameter's cancel field to true. This field also accepts a Promise (jQuery or native), which enables you to perform an asynchronous action before an item is deleted.

const widgetOptions = {
    onItemDeleting: function(e) {
        const d = $.Deferred();
        DevExpress.ui.dialog.confirm("Do you really want to delete the item?")
            .done(function(value) { 
                d.resolve(!value);
            })
            .fail(d.reject);
        e.cancel = d.promise();
    }
}

Note that the onItemDeleted and onItemDeleting handlers are not executed if an item is deleted from the data source without using the UI component's UI or API.

See Also

• itemDragging
• List - Handle Reordering-Related Events

See Also

• List - Touch-Screen Gestures

The following example shows how to subscribe to component property changes:

$(function() {
    $("#listContainer").dxList({
        // ...
        onOptionChanged: function(e) {
            if(e.name === "changedProperty") {
                // handle the property change here
            }
        }
    });
});

<dx-list ...
    (onOptionChanged)="handlePropertyChange($event)"> 
</dx-list>

import { Component } from '@angular/core'; 

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

export class AppComponent { 
    // ...
    handlePropertyChange(e) {
        if(e.name === "changedProperty") { 
            // handle the property change here
        }
    }
}

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 { }  

<template> 
    <DxList ...
        @option-changed="handlePropertyChange"
    />            
</template> 

<script>  
import 'devextreme/dist/css/dx.light.css'; 
import DxList from 'devextreme-vue/list'; 

export default { 
    components: { 
        DxList
    }, 
    // ...
    methods: { 
        handlePropertyChange: function(e) {
            if(e.name === "changedProperty") {
                // handle the property change here
            }
        }
    } 
} 
</script> 

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

import List from 'devextreme-react/list'; 

const handlePropertyChange = (e) => {
    if(e.name === "changedProperty") {
        // handle the property change here
    }
}

export default function App() { 
    return ( 
        <List ...
            onOptionChanged={handlePropertyChange}
        />        
    ); 
} 

See Also

• Paging

See Also

• List - Touch-Screen Gestures

See Also

• List - Handle Scrolling-Related Events

See Also

• selectAllMode
• List - Handle Selection-Related Events

See Also

• List - Localization

View Demo

See Also

• List - Paging

See Also

• List - Localization

See Also

• List - Localization

If the property is set to true, list data is refreshed each time you pull down and release list contents.

See Also

• List - Touch-Screen Gestures

See Also

• List - Localization

View Demo

See Also

• push(changes) in: ArrayStore | CustomStore | LocalStore | ODataStore
• DataSource.reshapeOnPush

When this property is set to true, the UI component text flows from right to left, and the layout of elements is reversed. To switch the entire application/site to the right-to-left representation, assign true to the rtlEnabled field of the object passed to the DevExpress.config(config) method.

DevExpress.config({
    rtlEnabled: true
});

DataGrid Demo Navigation UI Demo Editors Demo

See Also

• List - Scrolling - User Interaction

See Also

• List - Scrolling - User Interaction

See Also

• List - Scrolling - User Interaction

See the TextBox Configuration for properties you can specify in this object.

View Demo

See Also

• Searching

If you need to search several fields, assign an array of field names to this property.

searchExpr: ["firstName", "lastName"]

View Demo

View Demo

The selectAllMode specifies how records should be selected on clicking the "Select All" check box. The following modes are available:

• "page"
  Selects items on the currently rendered pages.

• "allPages"
  Selects items on all pages.

View Demo

See Also

• List - Selection - User Interaction

If you enable selection and selection controls in the List component, checkboxes appear near each item. Assign true to this property to allow users to click anywhere on an item to select it, or false to select List items only by checking checkboxes.

View Demo

The item keys can be specified using the keyExpr property or the key property within the underlying Store.

See Also

• key in ArrayStore | CustomStore | LocalStore | ODataStore

This property accepts the following values.

• "none"
  Selection is disabled.

• "single"
  A user can select only a single item.

• "multiple"
  A user can select several items.

• "all"
  The multiple mode with a check box that selects/unselects all items.
  If paging is enabled, the select all check box selects only items that have been already loaded.

  NOTE

  The check box that selects/unselects all items is displayed only if the showSelectionControls property is enabled. Otherwise, the "all" mode works as "multiple".

View Demo

See Also

• List - Selection - User Interaction

Setting this property makes sense only when the useNativeScrolling property is set to false.

See Also

• List - Scrolling - User Interaction

View Demo

See Also

• List - Selection - User Interaction

The value of this property will be passed to the tabindex attribute of the HTML element that underlies the UI component.

See Also

• List - Scrolling - User Interaction

This property accepts a value of one of the following types:

• Number
  The width in pixels.

• String
  A CSS-accepted measurement of width. For example, "55px", "20vw", "80%", "auto", "inherit".

• Function (deprecated since v21.2)
  Refer to the W0017 warning description for information on how you can migrate to viewport units.