JavaScript/jQuery PieChart - 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() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        series: {
            argumentField: 'fruit',
            valueField: 'year2014',
            name: '2014'
        }
    });
});
Angular
HTML
TypeScript
<dx-pie-chart [dataSource]="fruitProduction">
    <dxi-series
        argumentField="fruit"
        valueField="year2014"
        name="2014">
    </dxi-series>
</dx-pie-chart>
import { DxPieChartModule } 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: [
        // ...
        DxPieChartModule
    ],
    // ...
})
Vue
App.vue
<template> 
    <DxPieChart ... 
        :data-source="fruitProduction">
        <DxSeries
            argument-field="fruit"
            value-field="year2014"
            name="2014"
        />
    </DxPieChart>
</template>

<script>
import DxPieChart, {
    DxSeries
} from 'devextreme-vue/pie-chart';

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

export default {
    components: {
        DxPieChart,
        DxSeries
    },

    data() {
        return {
            fruitProduction
        };
    }
}
</script>
React
App.js
import React from 'react';
import PieChart, {
    Series
} from 'devextreme-react/pie-chart';

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

const App = () => {
    return (
        <PieChart ... 
            dataSource={fruitProduction}>
            <Series
                argumentField="fruit"
                valueField="year2014"
                name="2014"
            />
        </PieChart>
    );
};

export default App;

The PieChart may contain several series that have the same argument field. In this case, you can assign the field's name 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() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit'
        },
        series: [
            { valueField: 'year2014', name: '2014' },
            { valueField: 'year2015', name: '2015' },
            { valueField: 'year2016', name: '2016' }
        ]
    });
});
Angular
HTML
TypeScript
<dx-pie-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-pie-chart>
import { DxPieChartModule } 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: [
        // ...
        DxPieChartModule
    ],
    // ...
})
Vue
App.vue
<template> 
    <DxPieChart ...
        :data-source="fruitProduction">
        <DxCommonSeriesSettings argument-field="fruit" />
        <DxSeries
            value-field="year2014"
            name="2014"
        />
        <DxSeries
            value-field="year2015"
            name="2015"
        />
        <DxSeries
            value-field="year2016"
            name="2016"
        />
    </DxPieChart>
</template>

<script>
import DxPieChart, {
    DxCommonSeriesSettings,
    DxSeries
} from 'devextreme-vue/pie-chart';

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

export default {
    components: {
        DxPieChart,
        DxCommonSeriesSettings,
        DxSeries
    },

    data() {
        return {
            fruitProduction
        };
    }
}
</script>
React
App.js
import React from 'react';
import PieChart, {
    CommonSeriesSettings,
    Series
} from 'devextreme-react/pie-chart';

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

const App = () => {
    return (
        <PieChart ...
            dataSource={fruitProduction}>
            <CommonSeriesSettings argumentField="fruit" />
            <Series
                valueField="year2014"
                name="2014"
            />
            <Series
                valueField="year2015"
                name="2015"
            />
            <Series
                valueField="year2016"
                name="2016"
            />
        </PieChart>
    );
};

export default App;
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.

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() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit',
            valueField: 'produced'
        },
        seriesTemplate: {
            nameField: 'year'
        }
    });
});
Angular
HTML
TypeScript
<dx-pie-chart [dataSource]="fruitProduction">
    <dxo-common-series-settings
        argumentField="fruit"
        valueField="produced">
    </dxo-common-series-settings>
    <dxo-series-template
        nameField="year">
    </dxo-series-template>
</dx-pie-chart>
import { DxPieChartModule } 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: [
        // ...
        DxPieChartModule
    ],
    // ...
})
Vue
App.vue
<template> 
    <DxPieChart ...
        :data-source="fruitProduction">
        <DxCommonSeriesSettings
            argument-field="fruit"
            value-field="produced"
        />
        <DxSeriesTemplate name-field="year" />
    </DxPieChart>
</template>

<script>
import DxPieChart, {
    DxCommonSeriesSettings,
    DxSeriesTemplate
} from 'devextreme-vue/pie-chart';

const 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 }
];

export default {
    components: {
        DxPieChart,
        DxCommonSeriesSettings,
        DxSeriesTemplate
    },

    data() {
        return {
            fruitProduction
        };
    }
}
</script>
React
App.js
import React from 'react';
import PieChart, {
    CommonSeriesSettings,
    SeriesTemplate
} from 'devextreme-react/pie-chart';

const 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 }
];

const App = () => {
    return (
        <PieChart ...
            dataSource={fruitProduction}>
            <CommonSeriesSettings
                argumentField="fruit"
                valueField="produced"
            />
            <SeriesTemplate nameField="year" />
        </PieChart>
    );
};

export default App;

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 the function.

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

$(function() {
    $("#pieChartContainer").dxPieChart({
        dataSource: fruitProduction,
        commonSeriesSettings: {
            argumentField: 'fruit',
            valueField: 'produced'
        },
        seriesTemplate: {
            nameField: 'year',
            customizeSeries: function(seriesName) {
                // Colors the series "2016" in blue
                return seriesName == 2016 ? { color: 'blue' } : { }
            }
        }
    });
});
Angular
HTML
TypeScript
<dx-pie-chart [dataSource]="fruitProduction">
    <dxo-common-series-settings
        argumentField="fruit"
        valueField="produced">
    </dxo-common-series-settings>
    <dxo-series-template
        nameField="year"
        [customizeSeries]="customizeSeries">
    </dxo-series-template>
</dx-pie-chart>
import { DxPieChartModule } from "devextreme-angular";
// ...
export class AppComponent {
    fruitProduction = [
        { fruit: "Apples", year: 2014, produced: 84 },
        // ...
    ];
    customizeSeries(seriesName: string) {
        // Colors the series "2016" in blue
        return seriesName == 2016 ? { color: 'blue' } : { }
    }
}
@NgModule({
    imports: [
        // ...
        DxPieChartModule
    ],
    // ...
})
Vue
App.vue
<template> 
    <DxPieChart ...
        :data-source="fruitProduction">
        <DxCommonSeriesSettings
            argument-field="fruit"
            value-field="produced"
        />
        <DxSeriesTemplate
            :customize-series="customizeSeries"
            name-field="year"
        />
    </DxPieChart>
</template>

<script>
import DxPieChart, {
    DxCommonSeriesSettings,
    DxSeriesTemplate
} from 'devextreme-vue/pie-chart';

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

export default {
    components: {
        DxPieChart,
        DxCommonSeriesSettings,
        DxSeriesTemplate
    },

    data() {
        return {
            fruitProduction
        };
    },

    methods: {
        customizeSeries(seriesName) {
            // Colors the series "2016" in blue
            return seriesName == 2016 ? { color: 'blue' } : { }
        }
    }
}
</script>
React
App.js
import React from 'react';
import PieChart, {
    CommonSeriesSettings,
    SeriesTemplate
} from 'devextreme-react/pie-chart';

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

const customizeSeries = (seriesName) => {
    // Colors the series "2016" in blue
    return seriesName == 2016 ? { color: 'blue' } : { }
};

const App = () => {
    return (
        <PieChart ...
            dataSource={fruitProduction}>
            <CommonSeriesSettings
                argumentField="fruit"
                valueField="produced"
            />
            <SeriesTemplate
                nameField="year"
                customizeSeries={customizeSeries}
            />
        </PieChart>
    );
};

export default App;
See Also