Highcharts Official React Integration (Legacy)

Common errors

• TypeError: Cannot read properties of undefined (reading 'chart')

  cause Highcharts modules were not correctly initialized or the `highcharts` prop was not passed to `HighchartsReact`.
  fix Ensure `import Highcharts from 'highcharts';` is present, Highcharts modules are applied (`MyModule(Highcharts);`), and `<HighchartsReact highcharts={Highcharts} options={options} />` is used correctly.

• Highcharts is not defined

  cause The core Highcharts library was not imported, or its global presence (if not using the prop) was not guaranteed, especially in older CJS setups or non-modular environments.
  fix Always explicitly import `Highcharts` from the `highcharts` package and pass it via the `highcharts` prop to `HighchartsReact`. Avoid relying on `Highcharts` being globally available via `window`.

• TypeError: can't access property "setHighcharts", etc. with Highcharts CDN.

  cause Attempting to use Highcharts from a CDN or non-module build in conjunction with the React wrapper, leading to module resolution or instance-sharing issues.
  fix For modular React applications, install Highcharts via npm (`npm install highcharts`) and import it as a module (`import Highcharts from 'highcharts';`) rather than relying on CDN-loaded global Highcharts instances.

• Chart not updating when props or state change.

  cause The `options` object passed to `HighchartsReact` was mutated directly instead of providing a new, immutable object, or the `oneToOne` update parameter was not correctly handled in older versions.
  fix Always create a new `options` object (e.g., using spread syntax) when making changes that should trigger a chart update. In older versions of the wrapper, `oneToOne={true}` might have been required as a prop, though this is often default behavior now.

Warnings

• breaking The `highcharts-react-official` package has been deprecated in favor of the new, officially supported `@highcharts/react` package (v4+). New projects should use `@highcharts/react` for improved API, ESM support, and better developer experience. Migration involves uninstalling the old package, installing the new one, and updating import statements and component props.
  Fix: For new projects, use `npm install @highcharts/react highcharts react react-dom` and follow the migration guide to update imports and component structure. For existing projects, consider upgrading or ensuring compatibility with `highcharts-react-official`'s specific requirements.
• gotcha Highcharts mutates the chart `options` object internally. To ensure React's reconciliation works correctly and to avoid unexpected behavior, always pass immutable options objects or create new objects when updating chart properties.
  Fix: When updating chart options, create a new options object using spread syntax (`{ ...prevOptions, series: [...] }`) instead of directly modifying the existing one. This signals to React and the wrapper that a change has occurred.
• gotcha Highcharts modules (e.g., exporting, drilldown, boost) are not automatically loaded and applied. They must be explicitly imported and then initialized by calling the module function with the Highcharts core instance.
  Fix: Import each required module (e.g., `import HighchartsExporting from 'highcharts/modules/exporting';`) and then apply it to the Highcharts instance, typically wrapped in a check for SSR: `if (typeof Highcharts === 'object') { HighchartsExporting(Highcharts); }`.
• gotcha Highcharts is designed to run in a browser environment with access to the `window` and `document` objects. Server-Side Rendering (SSR) frameworks like Next.js will encounter errors if Highcharts components or modules are imported and executed on the server without proper safeguards.
  Fix: Use dynamic imports with `ssr: false` for Next.js, or conditionally render your chart component only after the component has mounted to ensure it runs only on the client-side (e.g., using `useEffect` or `useState` to track client-side rendering). Wrap module initializations in `if (typeof Highcharts === 'object')`.
• breaking `highcharts-react-official` v3.x requires React `^16.8.0` and Highcharts `^6.0.0`. Attempting to use significantly newer React versions (e.g., React 18) or very old Highcharts versions might lead to compatibility issues or require specific configurations. The newer `@highcharts/react` package explicitly requires React 18 and Highcharts 12.2+.
  Fix: Ensure your `react`, `react-dom`, and `highcharts` peer dependencies match the specified versions for `highcharts-react-official` (React >=16.8.0, Highcharts >=6.0.0). For React 18+, consider migrating to the `@highcharts/react` package.

Install

• npm install highcharts-react-official npm
• yarn add highcharts-react-official yarn
• pnpm add highcharts-react-official pnpm

Imports

• HighchartsReact
  wrong:

  import HighchartsReact from 'highcharts-react-official';

  correct:

  import { HighchartsReact } from 'highcharts-react-official';

  While a default export `import HighchartsReact from 'highcharts-react-official'` might work in JavaScript, the named import is generally preferred, especially when using TypeScript, and aligns with modern module practices. The newer `@highcharts/react` package exclusively uses named exports.
• Highcharts (core library)
  wrong:

  const Highcharts = require('highcharts');

  correct:

  import Highcharts from 'highcharts';

  The core Highcharts library should be imported separately and passed as a prop to `HighchartsReact`. ESM imports are standard for modern React applications. CommonJS `require` should be avoided for modern projects.
• Highcharts modules
  wrong:

  import 'highcharts/modules/exporting';

  correct:

  import HighchartsExporting from 'highcharts/modules/exporting';
  // Apply module to Highcharts instance
  if (typeof Highcharts === 'object') { HighchartsExporting(Highcharts); }

  Highcharts modules are functions that extend the Highcharts object. They must be imported and then explicitly called with the Highcharts instance. Simply importing the module path might not correctly initialize it, especially in SSR environments or with aggressive tree-shaking. Always wrap module application in a `typeof Highcharts === 'object'` check for SSR compatibility.

Quickstart

This quickstart renders a basic Highcharts line chart, demonstrates how to import and apply a Highcharts module (Exporting), and shows how to update chart data reactively using React's `useState` hook. It also correctly passes the Highcharts instance and handles potential SSR issues for module loading.

import React, { useRef, useEffect, useState } from 'react';
import Highcharts from 'highcharts';
import HighchartsExporting from 'highcharts/modules/exporting';
import HighchartsReact from 'highcharts-react-official';

// Initialize Highcharts modules if Highcharts object is available
if (typeof Highcharts === 'object') {
  HighchartsExporting(Highcharts);
}

const MyChartComponent = () => {
  const chartComponentRef = useRef(null);
  const [options, setOptions] = useState({
    title: { text: 'My Sample Chart' },
    series: [{
      type: 'line',
      data: [1, 2, 4, 6, 8, 7, 5, 3, 2, 1]
    }],
    chart: {
      height: 400,
      width: 600
    },
    credits: { enabled: false },
    exporting: { enabled: true }
  });

  // Example of updating data after some time
  useEffect(() => {
    const timer = setTimeout(() => {
      setOptions(prevOptions => ({
        ...prevOptions,
        series: [{
          ...prevOptions.series[0],
          data: [5, 7, 9, 8, 6, 4, 2, 1, 3, 5]
        }]
      }));
    }, 3000);
    return () => clearTimeout(timer);
  }, []);

  return (
    <div>
      <h2>Highcharts with React</h2>
      <HighchartsReact
        highcharts={Highcharts}
        options={options}
        ref={chartComponentRef}
      />
      <p>This chart demonstrates basic line series, module integration (exporting), and reactive updates via component state.</p>
    </div>
  );
};

export default MyChartComponent;