JavaScript/jQuery Chart - Bind Series to Data

This article describes two ways of binding series to data. To decide which way to use, check whether or not names for series are provided by a data source field. If so, you need to use a series template. Otherwise, you can bind series to data directly. For example, assume that you have the following data source.

JavaScript
var fruitProduction = [
    { fruit: "Apples", year: 2014, produced: 84 },
    { fruit: "Apples", year: 2015, produced: 82 },
    { fruit: "Apples", year: 2016, produced: 90 },
    { fruit: "Oranges", year: 2014, produced: 72 },
    { fruit: "Oranges", year: 2015, produced: 70 },
    { fruit: "Oranges", year: 2016, produced: 76 }
];

Depending on the configuration, this data source can produce either two series, named "Apples" and "Oranges", or three series: "2014", "2015" and "2016", but in both these cases, these names are provided by a data source field: fruit or year respectively. This is the case when you need to use a series template. Consider another data source.

JavaScript
var fruitProduction = [
    { fruit: "Apples",  year2014: 84, year2015: 82, year2016: 90 },
    { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 }
];

In this case, you can have up to three series bound to the year2014, year2015 and year2016 fields respectively, but note that there is no data field that provides names for them. Instead, you need to specify the names using the name property. This is the case when you can bind series to data directly.

Directly

To bind a series to data directly, specify which data source field provides arguments and which provides values. For this purpose, use the argumentField and valueField properties of the series configuration object.

jQuery
JavaScript
var fruitProduction = [
    { fruit: "Apples",  year2014: 84, year2015: 82, year2016: 90 },
    { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 }
];

$(function() {
    $("#chartContainer").dxChart({
        dataSource: fruitProduction,
        series: {
            argumentField: 'fruit',
            valueField: 'year2014',
            name: '2014'
        }
    });
});
Angular
HTML
TypeScript
<dx-chart [dataSource]="fruitProduction">
    <dxi-series
        argumentField="fruit"
        valueField="year2014"
        name="2014">
    </dxi-series>
</dx-chart>
import { DxChartModule } from "devextreme-angular";
// ...
export class AppComponent {
    fruitProduction = [
        { fruit: "Apples",  year2014: 84, year2015: 82, year2016: 90 },
        { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 }
    ];
}
@NgModule({
    imports: [
        // ...
        DxChartModule
    ],
    // ...
})

Commonly, a chart contains several series, and many of them have the same argument field. In this case, you can assign the name of this field to the argumentField property of the commonSeriesSettings object.

jQuery
JavaScript
var fruitProduction = [
    { fruit: "Apples",  year2014: 84, year2015: 82, year2016: 90 },
    { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 }
];

$(function() {
    $("#chartContainer").dxChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit'
        },
        series: [
            { valueField: 'year2014', name: '2014' },
            { valueField: 'year2015', name: '2015' },
            { valueField: 'year2016', name: '2016' }
        ]
    });
});
Angular
HTML
TypeScript
<dx-chart [dataSource]="fruitProduction">
    <dxo-common-series-settings
        argumentField="fruit">
    </dxo-common-series-settings>
    <dxi-series valueField="year2014" name="2014"></dxi-series>
    <dxi-series valueField="year2015" name="2015"></dxi-series>
    <dxi-series valueField="year2016" name="2016"></dxi-series>
</dx-chart>
import { DxChartModule } from "devextreme-angular";
// ...
export class AppComponent {
    fruitProduction = [
        { fruit: "Apples",  year2014: 84, year2015: 82, year2016: 90 },
        { fruit: "Oranges", year2014: 72, year2015: 70, year2016: 76 }
    ];
}
@NgModule({
    imports: [
        // ...
        DxChartModule
    ],
    // ...
})

The following series types need more than one value field or additional data fields.

Bubble Series Demo Financial Series Demo Range Series Demo

See Also

Using a Series Template

To bind series to data using a series template, start with setting common properties for all resulting series in the commonSeriesSettings object. Particularly, make sure that you have set the argumentField and valueField.

NOTE
Certain series types need more than one value field or additional data fields to be specified. These series types are listed in the closing part of the Bind Series to Data Directly topic.

After that, use the seriesTemplate.nameField property to specify which data source field provides names for series.

jQuery
JavaScript
var fruitProduction = [
    { fruit: "Apples", year: 2014, produced: 84 },
    { fruit: "Apples", year: 2015, produced: 82 },
    { fruit: "Apples", year: 2016, produced: 90 },
    { fruit: "Oranges", year: 2014, produced: 72 },
    { fruit: "Oranges", year: 2015, produced: 70 },
    { fruit: "Oranges", year: 2016, produced: 76 }
];

$(function() {
    $("#chartContainer").dxChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit',
            valueField: 'produced', // or other data fields
            type: 'bar'
        },
        seriesTemplate: {
            nameField: 'year'
        }
    });
});
Angular
HTML
TypeScript
<dx-chart [dataSource]="fruitProduction">
    <dxo-common-series-settings
        argumentField="fruit"
        valueField="produced"
        type="bar">
    </dxo-common-series-settings>
    <dxo-series-template nameField="year"></dxo-series-template>
</dx-chart>
import { DxChartModule } from "devextreme-angular";
// ...
export class AppComponent {
    fruitProduction = [
        { fruit: "Apples", year: 2014, produced: 84 },
        { fruit: "Apples", year: 2015, produced: 82 },
        { fruit: "Apples", year: 2016, produced: 90 },
        { fruit: "Oranges", year: 2014, produced: 72 },
        { fruit: "Oranges", year: 2015, produced: 70 },
        { fruit: "Oranges", year: 2016, produced: 76 }
    ];
}
@NgModule({
    imports: [
        // ...
        DxChartModule
    ],
    // ...
})

If you need to change properties of a particular series, return an object with them from the seriesTemplate.customizeSeries function. This object will be merged with the commonSeriesSettings object. To identify a series, use the argument passed to this function.

jQuery
JavaScript
var fruitProduction = [
    { fruit: "Apples", year: 2014, produced: 84 },
    // ...
];

$(function() {
    $("#chartContainer").dxChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit',
            valueField: 'produced',
            type: 'bar'
        },
        seriesTemplate: {
            nameField: 'year',
            customizeSeries: function(seriesName) {
                // Changes the type of the series "2016" from the common "bar" to "line"
                return seriesName == 2016 ? { type: 'line' } : { }
            }
        }
    });
});
Angular
HTML
TypeScript
<dx-chart [dataSource]="fruitProduction">
    <dxo-common-series-settings
        argumentField="fruit"
        valueField="produced"
        type="bar">
    </dxo-common-series-settings>
    <dxo-series-template nameField="year" [customizeSeries]="customizeSeries"></dxo-series-template>
</dx-chart>
import { DxChartModule } from "devextreme-angular";
// ...
export class AppComponent {
    fruitProduction = [
        { fruit: "Apples", year: 2014, produced: 84 },
        // ...
    ];
    customizeSeries(seriesName: string) {
        // Changes the type of the series "2016" from the common "bar" to "line"
        return seriesName == 2016 ? { type: "line" } : { }
    }
}
@NgModule({
    imports: [
        // ...
        DxChartModule
    ],
    // ...
})

View Demo

See Also