Highcharts Component

The Highcharts Component allows the end-user to define a chart in the dashboard. Charts are generally used to visualize changing data.

How to start

We need to load the JavaScript and CSS files in the following order to get started.

1. Import

To use the Highcharts Component, you first have to load Highcharts as usual and the Dashboards to bind them together. The order of the imports is essential, so ensure the Dashboards module is imported after the Highcharts module.


    <script src="https://code.highcharts.com/highcharts.js"></script>
    <script src="https://code.highcharts.com/dashboards/dashboards.js"></script>
    <script src="https://code.highcharts.com/dashboards/modules/layout.js"></script>

Alternatively, you can use the NPM package.


    npm install highcharts

Then, import the package and the dedicated plugin to connect it to the dashboard.


    import * as Highcharts from 'highcharts';
    import * as Dashboards from '@highcharts/dashboards';
    import LayoutModule from '@highcharts/dashboards/modules/layout';
 
    LayoutModule(Dashboards);
 
    Dashboards.HighchartsPlugin.custom.connectHighcharts(Highcharts);
    Dashboards.PluginHandler.addPlugin(Dashboards.HighchartsPlugin);

2. CSS

From version v3.0.0, the Highcharts Component does not use styledMode by default, so there is no need to load the set of CSS styles to display Highcharts properly. Importing only Dashboards’ CSS file is enough: css @import url("https://code.highcharts.com/dashboards/css/dashboards.css");

You can enable the styled mode at any time by setting the styledMode option to true in your chart options and styling it according to the Highcharts styling guide .

3. Cell identifier

After loading the necessary files, define a cell using a unique identifier, for example renderTo: 'dashboard-col-0'.

You can find more information on creating a layout in the dashboard here .

4. Chart options

Declare all the chart options in the chartOptions object. For the full set of available options, see the Highcharts API


    chartOptions: {
        series: [{
            data: [1, 2, 3, 4]
        }]
    }

5. Chart type

The last thing you have to do is specify the type: 'Highcharts' in the component’s config. See the full example below.


Dashboards.board('container', {
    gui: {
        layouts: [{
            id: 'layout-1',
            rows: [{
                cells: [{
                    id: 'dashboard-col-0'
                }]
            }]
        }]
    },
    components: [{
        renderTo: 'dashboard-col-0',
        type: 'Highcharts',
        chartOptions: {
            series: [{
                data: [1, 2, 3, 4]
            }]
        }
    }]
});

Working with data

You can either define static data, as you would do in the basic Highcharts chart, or use the dataPool to connect some dynamic data. Here is the example .

If the data connector is connected, you can load the Highcharts’ dragDrop module to allow the user to change the value and sync the changes of this value with other components. Also, the editing is disabled by default if the series data is based on the columns in the connector, which were created by mathModifier. You can read more about it in the dataPool section.

Example using a DataConnector.


Dashboards.board('container', {
    dataPool: {
        connectors: [{
            id: 'Vitamin',
            type: 'CSV',
            options: {
                csv: `Food,Vitamin A,Iron
                Beef Liver,6421,6.5
                Lamb Liver,2122,6.5
                Cod Liver Oil,1350,0.9
                Mackerel,388,1
                Tuna,214,0.6`,
            },
        }]
    },
    gui: {
        layouts: [{
            id: 'layout-1',
            rows: [{
                cells: [{
                    id: 'dashboard-col-0'
                }]
            }]
        }]
    },
    components: [{
        renderTo: 'dashboard-col-0',
        type: 'Highcharts',
        connector: {
            id: 'Vitamin'
        },
        chartOptions: {
            title: {
                text: 'Example chart'
            }
        }
    }]
});

Assigning column data to series data

The data can be parsed through the columnAssignment option to map correct values from the connector to reflect them in the series. You can also declare which columns will be the point’s parameters. This is useful for series like OHLC, candlestick, column range, or arrange. The seriesId field is mandatory for properly displaying series (for instance, in the legend). Here is the example .

The data option can take three different types:

1. `string` one-dimensional

Column name containing the one-dimensional data.


columnAssignment: [{
    seriesId: 'mySeriesId',
    data: 'myData'
}]

2. `string[]` two-dimensional

Names of the columns that data will be used in the two-dimensional format.


columnAssignment: [{
    seriesId: 'mySeriesId',
    data: ['myX', 'myY']
}]

3. `Record<string, string>`

Object with the keys as series data key names and column names that will be used for the key-defined two-dimensional series data.


columnAssignment: [{
    seriesId: 'myStockSeriesId',
    data: {
        x: 'myX',
        open: 'myOpen',
        high: 'myHigh',
        low: 'myLow',
        close: 'myClose'
    },
}, {
    seriesId: 'myColumnSeriesId',
    data: {
        name: 'myNamesColumn',
        y: 'myYColumn',
        'dataLabels.style.visibility': 'myDataLabelVisibilityColumn'
    }
}]

Multiple connectors

The Highcharts Component also supports more than one data source. Therefore, the connector option must be configured as an array of objects rather than a single object.

Code sample:


components: [{
    type: 'Highcharts',
    connector: [{
        id: 'connector-1',
        columnAssignment: [ ... ]
    }, {
        id: 'connector-2',
        columnAssignment: [ ... ]
    }]
}]

Example:

Components synchronization

One of the many available options for the Highcharts Component is the sync option, which allows setting the synchronization of component states with each other. You can find more information about it in the sync article .

The sync can be an object configuration containing: highlight, visibility and extremes, which allow enabling or disabling the types of synchronization by passing the value true or false.

See demos of sync types below:

Highlight sync options

Highlight sync can have additional options:


sync: {
    highlight: {
        enabled: true,
        affectedSeriesId: 'series-1',
        highlightPoint: true,
        showTooltip: false,
        showCrosshair: true
    }
}

If you want to force highlight sync to always affect one specific series, use the affectedSeriesId option in the argument specifying the ID of that series. When undefined, empty or set to null, option assignment works by default based on the hovered column and column assignment.

Demo:

If you want to determine how the highlight of points on the chart should work (i.e. whether the hover state should be set for a marker, whether the crosshair should be synced and whether the tooltip should be shown), use the highlightPoint, showCrosshair and showTooltip options. Read more in the API docs .