Skip to main content

Configuration

This chapter will guide you through the set of Chart configuration options. It explores both common DHTMLX Chart properties actual for all chart types and the config options individual for particular types.

You need to set necessary properties from those listed below within the configuration object passed to the chart constructor function and thus adjust the chart settings to meet your needs.

Main properties​

DHTMLX Chart includes several configuration options that are mostly common for all chart types. They are:

type​

  • type - (string) defines the type of a chart to initialize; "bar", "x-bar" (for horizontal Bar chart), "line", "spline", "scatter", "area", "splineArea", "donut", "pie", "pie3D", "radar", "treeMap", and "calendarHeatMap"
const chart = new dhx.Chart("chart_container", {
    type:"bar"
});

scales​

  • scales - (object) defines configuration of chart scales
const chart = new dhx.Chart("chart_container", {
    scales:{}
});
info

It is necessary to configure scales for the Line, Spline, Bar, X-Bar, Area, SplineArea, Radar, or Scatter chart.

There are "left","right","top","bottom" and "radial" (for Radar chart) types of scales.

const chart = new dhx.Chart("chart_container", {
    type:"area",
    scales: {
        "bottom" : {
            text: 'month'
        },
        "left" : {
            padding: 10,
            max: 90
        }
    },
    series: [
        {
           value: 'company A',
           strokeWidth: 2
           // more options   
        }
    ]
});

Related sample: Chart. Scale title

Scales have both common and specific options. Check the full list of the available options for scales in the API reference.

series​

  • series - (array) defines configuration of chart series
const chart = new dhx.Chart("chart_container", {
    series:[]
});
info

The series configuration option is required for all types of charts.

Series present an array of objects each of which contains a number of properties for rendering a separate data set on a chart.

const chart = new dhx.Chart("chart_container", {
    type:"bar",
    scales: {
        "bottom" : {
            text: "month"
        },
        "left" : {}
    },
    series: [
        {
            id: "A",
            value: "company A",
            fill: "#394E79",
            stacked: stacked,
            color: "none"
        },
        {
            id: "B",
            value:"company B",
            fill: "#5E83BA",
            stacked: stacked,
            color: "none"
        }
    ]
});

Related sample: Chart. Point types

See the full list of configuration options for chart series in the API reference.

legend​

  • legend - (object) defines the configuration of a chart legend
const chart = new dhx.Chart("chart_container", {
    legend:{}
});
info

The legend configuration option is required for Treemap charts and is optional for other types of charts.

The legend object may contain a number of options that define its configuration.

const chart = new dhx.Chart("chart_container", {
    scales: {
        // scales config
    },
    series: [
        // list of series 
    ],
    legend: {
        series: ["A", "B", "C"],
        valign: "top",
        halign: "right"
    }    
});

Related Samples:

You can view the full list of the configuration options of chart legends in the API reference.

maxPoints​

  • maxPoints - (number) displays an average number of values in case a data set is too large to show all the values in the chart
const chart = new dhx.Chart("chart_container", {
    type:"line",
    maxPoints:100
});

Related sample: Chart. Max points

Line and Spline chart​

The configuration object of Line and Spline chart must include the following properties:

For example:

const config = {
    type: "line", // or "spline"
    scales: {
        "bottom": {
            text: "month"
        },
        "left": {
            maxTicks: 10,
            max: 100,
            min: 0
        }
    },
    series: [
        {
            id: "A",
            value: "company A",
            color: "#81C4E8",
            strokeWidth: 3
        },
        {
            id: "B",
            value: "company B",
            color: "#74A2E7",
            strokeWidth: 3
        },
        {
            id: "C",
            value: "company C",
            color: "#5E83BA",
            strokeWidth: 3
        }
    ],
    legend: {
        series: ["A", "B", "C"],
        halign: "right",
        valign: "top"
    }
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(dataset);

Related sample: Chart. Line chart initialization

Bar and X-Bar chart​

The configuration object of Bar and X-Bar chart must include the following properties:

For example:

const config = {
    type: "bar", // or type: "x-bar"
    scales: {
        "bottom": {
            text: "month"
        },
        "left": {
            maxTicks: 10,
            max: 100,
            min: 0
        }
    },
    series: [
        {
            id: "A",
            value: "company A",
            color: "#81C4E8",
            fill: "#81C4E8"
        },
        {
            id: "B",
            value: "company B",
            color: "#74A2E7",
            fill: "#74A2E7"
        },
        {
            id: "C",
            value: "company C",
            color: "#5E83BA",
            fill: "#5E83BA"
        }
    ],
    legend: {
        series: ["A", "B", "C"],
        halign: "right",
        valign: "top"
    }
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(dataset);

Related sample: Chart. Bar chart initialization

Area and SplineArea chart​

The configuration object of Area and SplineArea chart must include the following properties:

For example:

const config = {
    type: "area", // or "splineArea"
    scales: {
        "bottom": {
            text: "month"
        },
        "left": {
            maxTicks: 10,
            max: 100,
            min: 0
        }
    },
    series: [
        {
            id: "A",
            value: "company A",
            color: "#81C4E8",
            strokeWidth: 3
        },
        {
            id: "B",
            value: "company B",
            color: "#74A2E7",
            strokeWidth: 3
        },
        {
            id: "C",
            value: "company C",
            color: "#5E83BA",
            strokeWidth: 3
        }
    ],
    legend: {
        series: ["A", "B", "C"],
        halign: "right",
        valign: "top"
    }
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(dataset);

Related sample: Chart. Area chart initialization

Pie, Pie 3D and Donut chart​

The configuration object of Pie, Pie 3D and Donut chart must include the following properties:

For example:

const config = {
    type: "pie", // or type: "pie3D", or type: "donut"
    series: [
        {
            value: "value",
            color: "color",
            text: "month",
            stroke: "#FFFFFF",
            strokeWidth: 2
        }
    ],
    legend: {
        values: {
            text: "id",
            color: "color"
        },
        halign: "right",
        valign: "top"
    }
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(pie_dataset);

Related sample: Chart. Pie chart initialization

Radar chart​

The configuration object of Radar chart must include the following properties:

For example:

const config = {
    type: "radar",
    scales: {
        "radial": {
            value: "month",
            maxTicks: 10
        }
    },
    series: [
        {
            id: "A",
            value: "company A",
            color: "#81C4E8",
            pointColor: "#81C4E8"
        },
        {
            id: "B",
            value: "company B",
            color: "#74A2E7",
            pointColor: "#74A2E7"
        },
        {
            id: "C",
            value: "company C",
            color: "#5E83BA",
            pointColor: "#5E83BA"
        }
    ],
    legend: {
        series: ["A", "B", "C"],
        halign: "right",
        valign: "top"
    }
};

const chart = new dhx.Chart("chart", config);
chart.data.parse(dataset);

Related sample: Chart. Radar chart initialization

Scatter chart​

The configuration object of Scatter chart must include the following properties:

For example:

const config = {
    type: "scatter",
    scales: {
        bottom: {
            title: "value B",
            min: 0,
            max: 100,
            scalePadding: 25
        },
        left: {
            maxTicks: 10,
            title: "value A",
            max: 100
        }
    },
    series: [
        {
            id: "A_B",
            type: "scatter",
            value: "value A",
            valueY: "value B",
            color: "#81C4E8",
            pointType: "circle"
        },
        {
            id: "B_A",
            type: "scatter",
            value: "value B",
            valueY: "value A",
            color: "#74A2E7",
            pointType: "circle"
        }
    ],
    
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(dataset);

Related sample: Chart. Scatter chart initialization

Treemap chart​

The configuration object of Treemap chart must include the following properties:

With groups​

const treeMapData = [
    { id: "2021", name: "2021" },
    { id: "100", value: 50, name: "Outsourcing team", parent: "2021" },
    { id: "101", value: 100, name: "Product team", parent: "2021" },
    { id: "102", value: 10, name: "QA team", parent: "2021" },
    
    { id: "2020", name: "2020" },
    { id: "200", value: 32, name: "Outsourcing team", parent: "2020" },
    { id: "201", value: 4, name: "QA team", parent: "2020" },
    { id: "202", value: 35, name: "Product team", parent: "2020" },
];

const config = {
    type: "treeMap",
    series: [
        {
            value: "value",
            text: "name",
            stroke: "#eeeeee",
            strokeWidth: 1,
            tooltipTemplate: item => `${item[1]}: ${item[0]} employees`,
            direction: "desc",
        }
    ],
    legend: {
        type: "groupName",
        treeSeries: [
            { id: "2021", color: "#2A9D8F" },
            { id: "2020", color: "#78586F" },
            { id: "2019", color: "#E76F51" },
            { id: "2018", color: "#E5A910" },
            { id: "2017", color: "#11A3D0" },
        ],
        halign: "right",
        valign: "bottom",
    },
    data: treeMapData
};

const chart = new dhx.Chart("chart_container", config);

Related sample: Chart. Treemap chart with groups initialization

Without groups​

const treeMapData = [
       {
          "planet": "Mercury",
          "radius": "2440"
       },
       {
          "planet": "Venus",
          "radius": "6052"
       },
    ...
]

const config = {
    type: "treeMap",
    series: [
        {
            value: "radius",
            text: "planet",
            stroke: "#eeeeee",
            strokeWidth: 1,
            tooltipTemplate: item => `${item[1]} - ${item[0]}`,
        }
    ],
    legend: {
        type: "range",
        treeSeries: [
            { greater: 60000, color: "#237396" },
            { from: 50000, to: 60000, color: "#2780A8" },
            { from: 20000, to: 50000, color: "#3892A3" },
            { from: 6000, to: 20000, color: "#4DA3A0" },
            { less: 20000, color: "#67BF99" },
        ],
        halign: "right",
        valign: "top",
        direction: "row",
        size: 50,
    },
    data: treeMapData
};

const chart = new dhx.Chart("chart_container", config);

Related sample: Chart. Treemap chart initialization

Calendar heatmap chart​

The configuration object of Calendar heatmap chart must include the following properties:

For example

const heatMapData = [
    { id: "100", value: 50, date: new Date(2022, 2, 2) },
    { id: "201", value: 4, date: new Date(2022, 6, 15) },
    { id: "400", value: -14, date: new Date(2022, 9, 15) },
    { id: "500", value: 9, date: new Date(2022, 9, 20) },
    { id: "501", value: 100, date: new Date(2023, 1, 1) },
];

const config = {
    type: "calendarHeatMap",
    css: "dhx_widget--bordered",
    series: [
        {
            value: "value",
            date: "date",
            positiveColor: "#04deb6",
            negativeColor: "#ff457a",
            color: "#e5e5e5",
            weekStart: "monday",
            dateFormat: "%d %M %Y",
            tooltipTemplate: point => `${point[1]} contributions on ${point[0]}`,
            maxValue: 90,
            minValue: 0,
        }
    ],
    legend: {
        values: {
            text: "Calendar heatmap chart",
            tick: 5,
            majorTick: 2,
            step: 1,
            tickTemplate: value => `${value}c`,
        },
        halign: "right",
        valign: "top",
        margin: 0,
        size: 60,
    }
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(heatMapData);

Default range of dates​

The default range of dates for which Calendar heatmap chart will be shown is from the 1st of January of the minimal year found in the dataset to the 31st of December of the maximal year found in the dataset.

Custom range of dates​

If you have a large data set and don't need the chart to be shown for the whole period of time, you may change a range of dates to display the chart during the necessary period of time.

For this, use the startDate and endDate properties of the series property.

1. startDate & endDate​

Let's take the following data set:

const heatMapData = [
    { id: "100", value: 50, date: new Date(2022, 2, 2) },
    { id: "101", value: 100, date: new Date(2022, 4, 1) },
    { id: "200", value: 32, date: new Date(2022, 6, 1) },
    { id: "202", value: 35, date: new Date(2022, 7, 21) },
    { id: "400", value: -14, date: new Date(2022, 9, 15) },
    { id: "500", value: 9, date: new Date(2022, 9, 20) },
    { id: "501", value: 100, date: new Date(2023, 3, 1) },
    { id: "502", value: 40, date: new Date(2023, 4, 11) },
    { id: "503", value: 23, date: new Date(2023, 5, 6) },
];

and consider how the chart will be shown depending on the values of the start and end dates.

  • One year
const config = {
    type: "calendarHeatMap",
    series: [
        {
            value: "value",
            date: "date",
            startDate: "15/03/22",
            endDate: "15/03/23",
        }
    ],
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(heatMapData);

As a result, the chart will be displayed for the period from "15/03/22" to "15/03/23" inclusively.

  • One month
const config = {
    type: "calendarHeatMap",
    series: [
        {
            value: "value",
            date: "date",
            startDate: "01/03/22",
            endDate: "31/03/22",
        }
    ],
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(heatMapData);

As a result, the chart will be displayed for the period from "01/03/22" to "31/03/22" inclusively.

  • Any other period
const config = {
    type: "calendarHeatMap",
    series: [
        {
            value: "value",
            date: "date",
            startDate: "01/03/22",
            endDate: "01/07/24",
        }
    ],
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(heatMapData);

As a result, the chart will be displayed for the period from "01/03/22" to "01/07/24" inclusively.

2. startDate​

If you specify the start date but don't specify the end date, the period for which the chart will displayed depends both on the data set and the start date.

Example 1. Data in the range less than a year
const heatMapData = [
    { id: "100", value: 50, date: new Date(2022, 2, 2) },
    { id: "101", value: 100, date: new Date(2022, 4, 1) },
    { id: "200", value: 32, date: new Date(2022, 6, 1) },
    { id: "202", value: 35, date: new Date(2022, 7, 21) },
    { id: "500", value: 9, date: new Date(2022, 9, 20) },
    { id: "501", value: 100, date: new Date(2023, 1, 1) },
];

const config = {
    type: "calendarHeatMap",
    series: [
        {
            value: "value",
            date: "date",
            startDate: "15/03/22",
        }
    ],
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(heatMapData);

As a result, the chart will be displayed for the period from "15/03/22" to "14/03/23" inclusively (i.e. for one year).

Example 2. Data in the range more than a year
const heatMapData = [
    { id: "100", value: 50, date: new Date(2022, 2, 2) },
    { id: "101", value: 100, date: new Date(2022, 4, 1) },
    { id: "200", value: 32, date: new Date(2022, 6, 1) },
    { id: "202", value: 35, date: new Date(2022, 7, 21) },
    { id: "500", value: 9, date: new Date(2022, 9, 20) },
    { id: "501", value: 100, date: new Date(2023, 3, 1) },
    { id: "502", value: 40, date: new Date(2023, 4, 11) },
    { id: "503", value: 23, date: new Date(2023, 5, 6) },
];

const config = {
    type: "calendarHeatMap",
    series: [
        {
            value: "value",
            date: "date",
            startDate: "15/03/22",
        }
    ],
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(heatMapData);

As a result, the chart will be displayed for the period from "15/03/22" to "14/03/24" inclusively (i.e. for two years).

3. endDate​

If you specify the end date but don't specify the start date, the period for which the chart will displayed depends both on the data set and the end date. Note, that in this case the chart will start from the 1st of January of the minimal year found in the dataset.

const heatMapData = [
    { id: "100", value: 50, date: new Date(2022, 2, 2) },
    { id: "101", value: 100, date: new Date(2022, 4, 1) },
    { id: "200", value: 32, date: new Date(2022, 6, 1) },
    { id: "202", value: 35, date: new Date(2022, 7, 21) },
    { id: "300", value: 22, date: new Date(2022, 9, 6) },
    { id: "501", value: 100, date: new Date(2023, 3, 1) },
    { id: "502", value: 40, date: new Date(2023, 4, 11) },
    { id: "503", value: 23, date: new Date(2023, 5, 6) },
];

const config = {
    type: "calendarHeatMap",
    series: [
        {
            value: "value",
            date: "date",
            endDate: "15/05/23",
        }
    ],
};

const chart = new dhx.Chart("chart_container", config);
chart.data.parse(heatMapData);

As a result, the chart will be displayed for the period from "01/01/22" to "15/05/23" inclusively.