Highcharts Charting Library

Common errors

• ReferenceError: Highcharts is not defined

  cause The Highcharts library was not correctly imported or loaded into the execution scope before your application code attempted to use it.
  fix Ensure you are using `import Highcharts from 'highcharts';` at the top of your module file, or that the Highcharts script is properly included and available in the global scope if you're using a script tag.

• Highcharts error #17: This chart type is not supported in the current Highcharts setup. Did you forget to include a module?

  cause You are attempting to use a chart type (e.g., `stockChart`, `mapChart`, `ganttChart`, or specific series types like `treemap`) for which the corresponding Highcharts module has not been loaded or initialized.
  fix Identify the missing module required for your specific chart type (e.g., `highcharts/modules/stock.js`, `highcharts/modules/map.js`, `highcharts/modules/treemap.js`). Import it and ensure it's initialized by passing the main `Highcharts` object as described in the warnings.

• Error: Highcharts is free for non-commercial use, but commercial projects require a license.

  cause This verbatim message indicates that the Highcharts library's internal checks have determined that your usage context requires a commercial license, or your license key (if applicable) is incorrectly configured or missing.
  fix Verify your project's licensing status. If it's a commercial project, acquire a commercial license from highcharts.com. If you have a license, consult Highcharts documentation on how to correctly apply it for your specific setup (e.g., through `Highcharts.setOptions`).

Warnings

• breaking Highcharts is distributed under a proprietary license. It is free for non-commercial use, but commercial projects and applications require a valid commercial license. Using it commercially without a license is a breach of the licensing agreement.
  Fix: Review the Highcharts licensing terms at highcharts.com/license. For commercial use, purchase an appropriate license from Highcharts and ensure any required license keys or attributions are correctly integrated into your project.
• gotcha This npm package (`highcharts`) is primarily designed for client-side rendering within web browsers, typically bundled with tools like Webpack or Vite. It is not intended for generating static charts on a Node.js server-side environment directly.
  Fix: For server-side static chart generation (e.g., for reports or APIs), use the dedicated `highcharts-export-server` npm package, which is specifically built for that purpose.
• gotcha Highcharts modules (e.g., `highcharts/modules/exporting`, `highcharts/modules/stock`, `highcharts/modules/map`) do not always export named symbols directly. They typically extend the core `Highcharts` object or add functionality through side effects upon import or by being explicitly passed the `Highcharts` object.
  Fix: After importing the main `Highcharts` library, import the desired module (e.g., `import HighchartsExporting from 'highcharts/modules/exporting';`). Then, initialize the module by passing the main `Highcharts` object to it (e.g., `HighchartsExporting(Highcharts);`).
• gotcha While the complete `highcharts` npm package directory can appear large, its core library (`highcharts.js`) is highly optimized for performance and small bundle size (typically <100kB gzipped) when used with ES6 module support and tree-shaking. The larger package size includes all available modules, extensive TypeScript typings, and various loading options.
  Fix: Always use a modern JavaScript bundler (e.g., Webpack, Vite, Rollup) with ES6 imports to leverage tree-shaking capabilities. Only import the specific Highcharts modules and components you actively use to keep your final application bundle size minimal.

Install

• npm install highcharts npm
• yarn add highcharts yarn
• pnpm add highcharts pnpm

Imports

• Highcharts
  wrong:

  const Highcharts = require('highcharts');

  correct:

  import Highcharts from 'highcharts';

  Highcharts is typically imported as a default export. While CommonJS `require` can technically work, ESM imports are the standard for modern bundlers, facilitating tree-shaking and type inference.
• Highcharts modules (e.g., Exporting, Stock, Map)
  wrong:

  import { Exporting } from 'highcharts/modules/exporting';

  correct:

  import Highcharts from 'highcharts';
  import HighchartsExporting from 'highcharts/modules/exporting';
  HighchartsExporting(Highcharts);

  Highcharts modules typically extend the main Highcharts object via side effects upon import or by being passed the `Highcharts` object directly, rather than exporting specific named symbols themselves. Ensure the main `Highcharts` object is passed if the module expects it for initialization.
• Options (TypeScript type)
  wrong:

  import { Options } from 'highcharts';

  correct:

  import type { Options } from 'highcharts';

  The `Options` type is exclusively used for strictly typing chart configuration objects in TypeScript. It's a type-only import and should not be imported at runtime, hence the `type` keyword.

Quickstart

This quickstart initializes Highcharts with two commonly used modules (exporting for data/image export and series-label for better readability). It then renders a basic line chart displaying temperature trends, demonstrating a typical setup for a modern web application using TypeScript and Highcharts.

import Highcharts from 'highcharts';
import HighchartsExporting from 'highcharts/modules/exporting';
import HighchartsSeriesLabel from 'highcharts/modules/series-label';

// Initialize modules by passing the Highcharts instance to them
// This attaches their functionality to the core Highcharts object.
HighchartsExporting(Highcharts);
HighchartsSeriesLabel(Highcharts);

// Create a container element where the chart will be rendered
document.body.innerHTML = '<div id="container" style="width: 100%; height: 400px; margin-top: 20px;"></div>';

// Define the chart configuration using TypeScript types for clarity and strong typing
const chartOptions: Highcharts.Options = {
    chart: {
        type: 'line',
        renderTo: 'container',
        zoomType: 'x' // Enable zooming along the X-axis
    },
    title: {
        text: 'Annual Temperature Trends',
        align: 'left'
    },
    subtitle: {
        text: 'Source: World Weather Data',
        align: 'left'
    },
    xAxis: {
        categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
        title: { text: 'Month' }
    },
    yAxis: {
        title: {
            text: 'Temperature (°C)',
        }
    },
    tooltip: {
        valueSuffix: '°C' // Add unit to tooltip values
    },
    plotOptions: {
        series: {
            label: {
                connectorAllowed: false // Disable connector lines for series labels
            },
            pointStart: 0 // Start points from category index 0
        }
    },
    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]
        } as Highcharts.SeriesLineOptions, // Type assertion for specific series type
        {
            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]
        } as Highcharts.SeriesLineOptions
    ],
    responsive: {
        rules: [{
            condition: {
                maxWidth: 500
            },
            chartOptions: {
                legend: {
                    layout: 'horizontal',
                    align: 'center',
                    verticalAlign: 'bottom'
                }
            }
        }]
    },
    credits: {
        enabled: false // Commonly disabled for cleaner integration in applications
    },
    exporting: {
        enabled: true // Enables the download CSV, PNG, PDF options provided by the module
    }
};

// Create the chart instance by passing the configuration options
Highcharts.chart(chartOptions);