DevExtreme React - DataSource Props

This section describes options that configure the DataSource.

NOTE

The DataSource allows specifying CustomStore options in its configuration object, as shown in the following code:

jQuery
JavaScript
var infiniteList = new DevExpress.data.DataSource({
    load: function (loadOptions) {
        // Loading data objects
    },
    byKey: function (key) {
        // Retrieving a data object by key
    }
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    infiniteList: DataSource;
    constructor() {
        this.infiniteList = new DataSource({
            load: (loadOptions) => {
                // Loading data objects
            },
            byKey: (key) => {
                // Retrieving a data object by key
            }
        });
    }
}

customQueryParams

Custom parameters that should be passed to an OData service with the load query. Available only for the ODataStore.

Type:

Object

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    store: {
        type: "odata",
        // ODataStore is configured here
    },
    customQueryParams: {
        param: "value"
    }
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
import ODataStore from "devextreme/data/odata/store";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            store: new ODataStore({
                // ODataStore is configured here
            }),
            customQueryParams: {
                param: "value"
            }
        });
    }
}
See Also

expand

Specifies the navigation properties to be loaded with the OData entity. Available only for the ODataStore.

Type:

Array<String>

|

String

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    store: {
        type: "odata",
        // ODataStore is configured here
    },
    expand: ["PropertyName1", "PropertyName2"]
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
import ODataStore from "devextreme/data/odata/store";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            store: new ODataStore({
                // ODataStore is configured here
            }),
            expand: ["PropertyName1", "PropertyName2"]
        });
    }
}
ASP.NET MVC Controls
Razor C#
Razor VB
@(Html.DevExtreme().WidgetName()
    .DataSource(ds => ds.OData()
        .Expand("PropertyName1", "PropertyName2")
    )
)
@(Html.DevExtreme().WidgetName() _
    .DataSource(Function(ds)
        Return ds.OData() _
                 .Expand("PropertyName1", "PropertyName2")
    End Function)
)
See Also

filter

Specifies data filtering conditions.

Type:

Filter Expression

Possible variants:

  • Binary filter

    [ "field", "=", 3 ]

  • Unary filter

    [ "!", [ "field", "=", 3 ] ]

  • Complex filter

    [
    [ "field", "=", 10 ],
    "and",
    [
        [ "otherField", "<", 3 ],
        "or",
        [ "otherField", ">", 11 ]
    ]
]
jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    // ...
    filter: [ "count", "<", "10" ]
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            // ...
            filter: [ "count", "<", "10" ]
        });
    }
}
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().WidgetName()
    .DataSourceOptions(dso => dso
        .Filter("[ 'count', '<', '10' ]")
    )
)
NOTE
Filtering works when inputting a plain data structure only. However, if you need the filtering capability and hierarchical data, transform the plain data using the DataSource's group option.
See Also

group

Specifies data grouping options.

Type:

Group Expression

This option accepts one of the following:

  • String
    The field name to group by.

  • Object
    An object with the following fields:

    • selector: String
      The field name to group by.
    • desc: Boolean
      Sorts the selector field in descending order.

  • Array
    An array of strings and objects described above.

  • Function
    A function that returns the value to group by.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    // ...
    group: { selector: "LastName", desc: true },
    /* or as a function
    group: function(e) {
        // creates two custom groups
        return e.BirthYear < 1990 ? "Born before 1990" : "Born after 1990";
    } */
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            // ...
            group: { selector: "LastName", desc: true },
            /* or as a function
            group: function(e) {
                // creates two custom groups
                return e.BirthYear < 1990 ? "Born before 1990" : "Born after 1990";
            } */
        });
    }
}
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().WidgetName()
    .DataSourceOptions(dso => dso
        .Group("LastName", true)
        // === or as a function ===
        .Group("group_function")
    )
)

<script type="text/javascript">
    function group_function(e) {
        // creates two custom groups
        return e.BirthYear < 1990 ? "Born before 1990" : "Born after 1990";
    }
</script>
See Also

map

Specifies an item mapping function.

Type:

Function

Function parameters:
dataItem:

Object

An initial data item.

Return Value:

Object

A modified data item.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    store: {
        data: [{
            firstName: "John",
            lastName: "Smith"
        }]
    },
    map: function (dataItem) {
        return {
            fullName: dataItem.firstName + " " + dataItem.lastName
        }
    }
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
import ArrayStore from "devextreme/data/array_store";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            store: new ArrayStore({
                data: [{
                    firstName: "John",
                    lastName: "Smith"
                }]
            }),
            map: (dataItem) => {
                return {
                    fullName: dataItem.firstName + " " + dataItem.lastName
                }
            }
        });
    }
}
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().WidgetName()
    .DataSource(new [] {
        new {
            firstName = "John",
            lastName = "Smith"
        }
    })
    .DataSourceOptions(dso => dso
        .Map("dataSource_map")
    )
)

<script type="text/javascript">
    function dataSource_map (dataItem) {
        return {
            fullName: dataItem.firstName + " " + dataItem.lastName
        }
    }
</script>
See Also

onChanged

A function that is executed after data is loaded.

Type:

Function

Function parameters:
e:

Object

Information about changes.
Appears only when the push(changes) method is called and the reshapeOnPush option is false.

Object structure:
Name Type Description
changes

Array<any>

The received changes.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    onChanged: function () {
        // Your code goes here
    }
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            onChanged: () => {
                // Your code goes here
            }
        });
    }
}

onLoadError

A function that is executed when data loading fails.

Type:

Function

Function parameters:
error:

Object

The error.

Object structure:
Name Type Description
message

String

The error message.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    onLoadError: function (error) {
        console.log(error.message);
    }
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            onLoadError: (error) => {
                console.log(error.message);
            }
        });
    }
}

onLoadingChanged

A function that is executed when the data loading status changes.

Type:

Function

Function parameters:
isLoading:

Boolean

Indicates whether data is being loaded.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    onLoadingChanged: function (isLoading) {
        // Your code goes here
    }
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            onLoadingChanged: (isLoading) => {
                // Your code goes here
            }
        });
    }
}

pageSize

Specifies the maximum number of data items per page. Applies only if paginate is true.

Type:

Number

Default Value: 20

When data is grouped, this option specifies the number of groups per page. However, in the DataGrid and TreeList, it specifies the number of rows per page including group rows.

paginate

Specifies whether the DataSource loads data items by pages or all at once. Defaults to false if group is set; otherwise, true.

Type:

Boolean

Default Value: undefined

postProcess

Specifies a post processing function.

Type:

Function

Function parameters:
data:

Array<any>

The data loaded in the DataSource.

Return Value:

Array<any>

The data after processing.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    postProcess: function (data) {
        // Your code goes here
    }
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            postProcess: (data) => {
                // Your code goes here
            }
        });
    }
}
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().WidgetName()
    .DataSourceOptions(dso => dso
        .PostProcess("dataSource_postProcess")
    )
)

<script type="text/javascript">
    function dataSource_postProcess (data) {
        // Your code goes here
    }
</script>
See Also

pushAggregationTimeout

Specifies the period (in milliseconds) when changes are aggregated before pushing them to the DataSource.

Type:

Number

Default Value: undefined

When this option is undefined, the aggregation period is calculated automatically based on the rendering speed's measurements.

See Also

requireTotalCount

Specifies whether the DataSource requests the total count of data items in the storage.

Type:

Boolean

If this option is set to true, the Promise that the load() method returns is resolved with a second argument that contains the totalCount field:

JavaScript
var ds = new DevExpress.data.DataSource({
    // ...
    requireTotalCount: true
});

ds.load()
    .done(function (data, extra) {
        // "data" contains the loaded data
        // "extra" contains the "totalCount" field
    });
NOTE
When scrolling is infinite in the DataGrid, this option's value is always false.

reshapeOnPush

Specifies whether to reapply sorting, filtering, grouping, and other data processing operations after receiving a push.

Type:

Boolean

Default Value: false

View Demo

See Also

searchExpr

Specifies the fields to search.

Type:

getter

|

Array<getter>

In most cases, you should pass the name of a field by whose value data items are searched. Assign an array of field names to this option if you need to search elements by several field values.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    // ...
    searchExpr: ["firstName", "lastName"]
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            // ...
            searchExpr: ["firstName", "lastName"]
        });
    }
}

You can use this option along with searchOperation and searchValue to specify a simple filter. Use the filter option for more complex filtering conditions. Filters are combined if you specify them in both ways.

NOTE
Searching works when inputting a plain data structure only. However, if you need the searching capability and hierarchical data, transform the plain data using the DataSource's group option.
See Also

searchOperation

Specifies the comparison operation used in searching. The following values are accepted: "=", "<>", ">", ">=", "<", "<=", "startswith", "endswith", "contains", "notcontains".

Type:

String

Default Value: 'contains'

You can use this option with searchExpr and searchValue to specify a simple filter. Use the filter option for more complex filtering conditions. Filters are combined if you specify them in both ways.

In an ASP.NET MVC Control, specify this option using the FilterOperations enum that accepts the following values: Equal, NotEqual, LessThan, LessThanOrEqual, GreaterThan, GreaterThanOrEqual, NotContains, Contains, StartsWith, EndsWith and Between.

See Also

searchValue

Specifies the value to which the search expression is compared.

Type: any
Default Value: null

You can use this option along with searchExpr and searchOperation to specify a simple filter. Use the filter option for more complex filtering conditions. Filters are combined if you specify them in both ways.

See Also

select

Specifies the fields to select from data objects.

Type:

Select Expression

This option accepts one of the following:

  • String
    A field name to select.

  • Array of strings
    Several field names to select.

  • Function
    A function implementing custom selection logic.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    // ...
    select: ["firstName", "lastName", "birthDate"] 
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            // ...
            select: ["firstName", "lastName", "birthDate"] 
        });
    }
}
ASP.NET MVC Controls
Razor C#
@(Html.DevExtreme().WidgetName()
    .DataSourceOptions(dso => dso
        .Select("firstName", "lastName", "birthDate")
    )
)
See Also

sort

Specifies data sorting options.

Type:

Sort Expression

This option accepts one of the following:

  • String
    The field name to sort by.

  • Object
    An object with the following fields:

    • selector: String
      The field name to sort by.
    • desc: Boolean
      Sorts the selector field in descending order.

  • Array
    An array of strings and objects described above.

  • Function
    A function that returns the value to sort by.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    // ...
    sort: [
        "Position",
        { selector: "Last_Name", desc: true }
    ],
    /* or as a function
    sort: function(e) {
        // CEOs are always displayed at the top
        if(e.Position == "CEO") 
            return "!";
        else
            return e.Position;
    } */
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            // ...
            sort: [
                "Position",
                { selector: "Last_Name", desc: true }
            ],
            /* or as a function
            sort: function(e) {
                // CEOs are always displayed at the top
                if(e.Position == "CEO") 
                    return "!";
                else
                    return e.Position;
            } */
        });
    }
}
ASP.NET MVC Controls
Razor C#
Razor VB
@(Html.DevExtreme().WidgetName()
    .DataSourceOptions(dso => dso
        .Sort("Position", true) // for sorting by a single field
        // === or ===
        .Sort("sort_function")
        // === or ===
        .Sort(s => {             // for sorting by multiple fields
            s.AddSorting("Position");
            s.AddSorting("Last_Name", true);
        })
    )
)

<script type="text/javascript">
    function sort_function(e) {
        // CEOs are always displayed at the top
        if(e.Position == "CEO")
            return "!";
        else
            return e.Position;
    }
</script>
@(Html.DevExtreme().WidgetName() _
    .DataSourceOptions(Sub(dso)
        dso.Sort("Position", True) ' for sorting by a single field
        ' === or ===
        dso.Sort("sort_function")
        ' === or ===
        dso.Sort(Sub(s)             ' for sorting by multiple fields
            s.AddSorting("Position")
            s.AddSorting("Last_Name", True)
        End Sub)
    End Sub)
)

<script type="text/javascript">
    function sort_function(e) {
        // CEOs are always displayed at the top
        if(e.Position == "CEO")
            return "!";
        else
            return e.Position;
    }
</script>
See Also

store

Configures the store underlying the DataSource.

Type:

Store

|

Store Configuration

|

Array<any>

| any

This option accepts one of the following:

  • Store instance
    An ArrayStore, LocalStore, ODataStore, or CustomStore instance.

  • Store configuration object
    An ArrayStore, LocalStore, or ODataStore configuration object. Make sure to set the type option.

  • Array
    Assigning an array to the store option automatically creates an ArrayStore in the DataSource.

jQuery
JavaScript
var ds = new DevExpress.data.DataSource({
    store: new DevExpress.data.ArrayStore({
        // ArrayStore instance
    })
    // ===== or =====
    store: {
        type: "array",
        // ArrayStore configuration object
    }
    // ===== or =====
    store: [
        { id: 1, name: "John Doe" }
    ]
});
Angular
TypeScript
import DataSource from "devextreme/data/data_source";
import ArrayStore from "devextreme/data/array_store";
// ...
export class AppComponent {
    ds: DataSource;
    constructor() {
        this.ds = new DataSource({
            store: new ArrayStore({
                // ArrayStore instance
            })
            // ===== or =====
            store: {
                type: "array",
                // ArrayStore configuration object
            }
            // ===== or =====
            store: [
                { id: 1, name: "John Doe" }
            ]
        });
    }
}