HighCharts - Configuration Syntax

Highcharts - Configuration Syntax

This chapter demonstrates the fundamental structure used to configure and create a chart using the Highcharts API.

Step 1: Prepare the HTML Page

First, create an HTML page and include the Highcharts library (and any necessary modules) using your chosen method (CDN or local/NPM build). You also need an HTML element (typically a <div>) to serve as the container for your chart.

Example HTML Structure:

<!DOCTYPE html>
<html>
<head>
    <title>Highcharts Configuration Example</title>
    <!-- Include Highcharts via CDN -->
    <script src="https://code.highcharts.com/highcharts.js"></script>
    <!-- Optional modules -->
    <script src="https://code.highcharts.com/modules/accessibility.js"></script>
</head>
<body>
    <!-- This div will hold the chart -->
    <div id="chartContainer" style="width: 550px; height: 400px; margin: 0 auto"></div>

    <script>
        // Highcharts configuration script will go here
    </script>
</body>
</html>

The chartContainer div is where Highcharts will render the visualization.

Step 2: Create the Configuration Object

Highcharts is configured using a single JavaScript object (often referred to as options). This object contains properties that define every aspect of the chart, from its type and data to titles, axes, tooltips, and colors.

The core function to create a chart is Highcharts.chart():

Highcharts.chart('containerId', optionsObject);

Let’s break down some common configuration properties within the optionsObject:

chart

Defines basic chart properties like the type.

const chartOptions = {
    type: 'line' // e.g., 'bar', 'pie', 'scatter'
};

title

Sets the main title of the chart.

const titleOptions = {
    text: 'Monthly Average Temperature'
};

subtitle

Sets an optional subtitle.

const subtitleOptions = {
    text: 'Source: WorldClimate.com'
};

xAxis

Configures the horizontal axis (categories, labels, title, type like ‘datetime’).

const xAxisOptions = {
    categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
};

yAxis

Configures the vertical axis (title, labels, plot lines/bands). Can be an array for multiple axes.

const yAxisOptions = {
    title: {
        text: 'Temperature (°C)'
    },
    plotLines: [{
        value: 0,       // Position of the line
        width: 1,       // Line width
        color: '#808080' // Line color
    }]
};

tooltip

Customizes the pop-up information shown when hovering over data points.

const tooltipOptions = {
    valueSuffix: '°C', // Appends '°C' to the y-value
    shared: true // Show tooltip for all series at that x-value
};

legend

Configures the chart legend (layout, alignment, appearance).

const legendOptions = {
    layout: 'vertical',
    align: 'right',
    verticalAlign: 'middle'
};

series

This is where the actual data resides. It’s an array of series objects. Each object represents a distinct set of data (e.g., a line, a set of columns) and typically contains a name and a data array (or array of objects).

const seriesData = [
    {
        name: 'Tokyo',
        data: [7.0, 6.9, 9.5, 14.5, 18.2, 21.5, 25.2, 26.5, 23.3, 18.3, 13.9, 9.6]
    },
    {
        name: 'New York',
        data: [-0.2, 0.8, 5.7, 11.3, 17.0, 22.0, 24.8, 24.1, 20.1, 14.1, 8.6, 2.5]
    },
    // ... more series if needed
];

Step 3: Assemble and Initialize

Combine all the configuration parts into a single options object and pass it to Highcharts.chart().

// Combine all parts into one options object
const chartConfig = {
    chart: chartOptions,
    title: titleOptions,
    subtitle: subtitleOptions,
    xAxis: xAxisOptions,
    yAxis: yAxisOptions,
    tooltip: tooltipOptions,
    legend: legendOptions,
    series: seriesData,
    // Add other options like plotOptions, colors, accessibility, exporting etc.
    accessibility: {
        enabled: true // Best practice!
    }
};

// Initialize the chart when the DOM is ready
document.addEventListener('DOMContentLoaded', function () {
    const chart = Highcharts.chart('chartContainer', chartConfig);
});

Complete Example

Here is the full code for the example line chart:

highcharts_config_example.html

<!DOCTYPE html>
<html>
<head>
    <title>Highcharts Configuration Example</title>
    <script src="https://code.highcharts.com/highcharts.js"></script>
    <script src="https://code.highcharts.com/modules/accessibility.js"></script>
</head>
<body>
    <div id="chartContainer" style="width: 550px; height: 400px; margin: 0 auto"></div>

    <script>
        document.addEventListener('DOMContentLoaded', function () {
            const chartConfig = {
                chart: {
                    type: 'line'
                },
                title: {
                    text: 'Monthly Average Temperature'
                },
                subtitle: {
                    text: 'Source: WorldClimate.com'
                },
                xAxis: {
                    categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
                },
                yAxis: {
                    title: {
                        text: 'Temperature (°C)'
                    },
                    plotLines: [{
                        value: 0,
                        width: 1,
                        color: '#808080'
                    }]
                },
                tooltip: {
                    valueSuffix: '°C',
                    shared: true
                },
                legend: {
                    layout: 'vertical',
                    align: 'right',
                    verticalAlign: 'middle'
                },
                series: [
                    {
                        name: 'Tokyo',
                        data: [7.0, 6.9, 9.5, 14.5, 18.2, 21.5, 25.2, 26.5, 23.3, 18.3, 13.9, 9.6]
                    },
                    {
                        name: 'New York',
                        data: [-0.2, 0.8, 5.7, 11.3, 17.0, 22.0, 24.8, 24.1, 20.1, 14.1, 8.6, 2.5]
                    },
                    {
                        name: 'Berlin',
                        data: [-0.9, 0.6, 3.5, 8.4, 13.5, 17.0, 18.6, 17.9, 14.3, 9.0, 3.9, 1.0]
                    },
                    {
                        name: 'London',
                        data: [3.9, 4.2, 5.7, 8.5, 11.9, 15.2, 17.0, 16.6, 14.2, 10.3, 6.6, 4.8]
                    }
                ],
                accessibility: {
                    enabled: true
                }
            };

            const chart = Highcharts.chart('chartContainer', chartConfig);
        });
    </script>
</body>
</html>

Result Description

Opening this HTML file in a browser will render a line chart within the ‘chartContainer’ div. The chart displays the monthly average temperatures for four cities (Tokyo, New York, Berlin, London). The X-axis shows the months, and the Y-axis shows the temperature in Celsius, including a plot line at 0°C. Hovering over the chart will display tooltips showing the temperatures for all cities for a specific month. A legend on the right side identifies the color associated with each city.