Providing Highcharts instance as described in docs causes global re-renders

[jamie-perkins-sp]

Describe the bug

In the docs we are instructed to provide highcharts like so:

provideHighcharts({
      // Optional: Define the Highcharts instance dynamically
      instance: () => import('highcharts'),
      ...

vs in the demo app, it's provided like this:

provideHighcharts({
      instance: () => import('highcharts/esm/highcharts').then(m => m.default),
      ...

Providing it like import('highcharts') causes an issue, where if you have more than one chart on a page and one re-renders, they all re-render. You can reproduce this behavior in the demo app (steps below).

Expected behavior

Regardless of which way you provide the instance, you should not see global re-renders.

Demo

Follow the steps below in the demo app in this repo.

Steps required to recreate the problem in the demo:

1. In the demo app in this repo, run npm start
2. In app.config.ts, comment out the current instance:

// instance: () => import('highcharts/esm/highcharts').then(m => m.default),

3. add a new line:

instance: () => import('highcharts'),

4. Save, and return to the browser.
5. Click "Destroy chart" then "Recreate chart" on the first chart.
   • Both of the first 2 charts re-render.
   • The other charts are not rendering at all, I'm not sure what the issue is there.
6. Go back to app.config.ts, change the instance back to the ESM import and save.
   • all charts render
7. Do the same steps: Click "Destroy chart" then "Recreate chart" on the first chart.
   • Only the first chart re-renders.

[karolkolodziej]

Hi @jamie-perkins-sp — apologies for the late reply, this one slipped past me somehow.

One thing worth clarifying, as this can be a bit unintuitive when entering the Highcharts ecosystem: due to historical reasons, the highcharts entry point still resolves to the CommonJS build. So even though the project may be fully ESM-based, importing from highcharts does not automatically give you the ESM version.

To use the ESM build, the import path needs to be explicitly changed to:

import('highcharts/esm/highcharts').then(m => m.default)

This difference matters because the CommonJS and ESM builds expose slightly different module shapes. In Angular’s signal-based change detection, this can be interpreted as a new value, which may cause all chart subscribers to be notified and trigger global re-renders.

Using the ESM build is recommended because it provides:

• a stable module cache, guaranteeing the same instance reference across all charts
• better tree-shaking, resulting in a smaller bundle size

As part of this issue, we'll clarify this in the docs.