# @stackline/react-highcharts

> A maintained React 19 wrapper for Highcharts, Highstock, and Highmaps with native options, constructor switching, module helpers, refs, and realtime update modes.

[![npm version](https://img.shields.io/npm/v/@stackline/react-highcharts.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/react-highcharts)
[![license](https://img.shields.io/npm/l/@stackline/react-highcharts.svg?style=flat-square)](https://github.com/alexandroit/react-highcharts)
[![GitHub repository](https://img.shields.io/badge/GitHub-repository-181717?style=flat-square&logo=github)](https://github.com/alexandroit/react-highcharts)
[![Docs](https://img.shields.io/badge/docs-alexandro.net-0f766e?style=flat-square)](https://alexandro.net/docs/react/react-highcharts/)
[![Reddit community](https://img.shields.io/badge/community-r%2FStackline-ff4500?style=flat-square&logo=reddit&logoColor=white)](https://www.reddit.com/r/Stackline/)

**[Documentation](https://alexandro.net/docs/react/react-highcharts/)** | **[npm](https://www.npmjs.com/package/@stackline/react-highcharts)** | **[Issues](https://github.com/alexandroit/react-highcharts/issues)** | **[Repository](https://github.com/alexandroit/react-highcharts)**

**Current package version:** `19.1.4`

---

## Why this package?

`@stackline/react-highcharts` gives React 19 applications a small, predictable bridge to Highcharts.

The goal is not to hide Highcharts. Your application still owns the real Highcharts options object, the Highcharts instance, module registration, constructor choice, event callbacks, and native chart instance. The wrapper gives React a stable `<Chart>` component, typed props, ref access, resize-aware rendering, SSR-safe effects, module helper utilities, and update modes that avoid unnecessary full chart recreation.

The React 19 package family is intended for React `19.x` applications. Release `19.1.2` is validated with React `19.2.8` and Highcharts `13.0.2`. The validation app renders static chart examples, realtime market examples, and verifies that dynamic charts update existing Highcharts series instead of blinking through full object recreation.

## Compatibility

| Item | Value |
| --- | --- |
| Package | `@stackline/react-highcharts@19.1.4` |
| Peer: `highcharts` | `>=6.0.0 <=13.0.2` |
| Peer: `react` | `>=19.0.0 <20.0.0` |
| Peer: `react-dom` | `>=19.0.0 <20.0.0` |
| Runtime dependencies | None; framework peers are supplied by the application |
| Package format | ESM, CommonJS, and TypeScript declarations |




### React Version Compatibility

Each package family targets one React major. Keep the package major aligned with the React major used by your application.

| Package family | React family | Peer range | Install |
| :---: | :---: | :---: | :--- |
| `19.x` | React `19.x` | `>=19.0.0 <20.0.0` | `npm install @stackline/react-highcharts@19.1.4 highcharts@13.0.2 --save-exact` |
| `18.x` | React `18.x` | `>=18.0.0 <19.0.0` | `npm install @stackline/react-highcharts@18.0.0 highcharts@12.6.0 --save-exact` |
| `17.x` | React `17.x` | `>=17.0.0 <18.0.0` | `npm install @stackline/react-highcharts@17.0.0 highcharts@12.6.0 --save-exact` |

Each React major is released separately so every line can be tested with the matching React runtime and project template.



### Highcharts Compatibility

The React 19 validation app uses `highcharts@13.0.2`, which is the highest Highcharts version tested for this line.

The maintained Stackline React 19 line is published with a Highcharts peer range of `>=6.0.0 <=13.0.2` so applications get a clear compatibility ceiling while still keeping Highcharts as an application-owned peer dependency.

Highcharts 6 predates bundled TypeScript declarations. JavaScript applications can use it directly; TypeScript applications pinned to Highcharts 6 must also install the historical `@types/highcharts@5.0.44` declarations. Highcharts 7 and newer include their own declarations.

Highcharts 13 moved data sorting into a separate module. Applications that use `plotOptions.series.dataSorting` should register it during startup:

```tsx
const dataSortingModule = await import('highcharts/modules/data-sorting.js');
initHighchartsModules(Highcharts, dataSortingModule);
```

<a id="install"></a>

## Installation

```bash
npm install @stackline/react-highcharts highcharts
```

The package declares `highcharts`, `react`, and `react-dom` as peer dependencies so your application owns the Highcharts build, modules, license, and React runtime.

Use `npm install @stackline/react-highcharts@19.1.4 highcharts@13.0.2 --save-exact` when your release process pins exact dependency versions.

## Usage

### Setup

#### 1. Import Highcharts and the wrapper

```tsx
import Highcharts from 'highcharts';
import { Chart } from '@stackline/react-highcharts';
```

#### 2. Render the wrapper with native Highcharts options

```tsx
<Chart highcharts={Highcharts} options={options} />
```

### Basic Usage

#### 1. Render a chart

```tsx
import Highcharts from 'highcharts';
import { Chart } from '@stackline/react-highcharts';

const options: Highcharts.Options = {
  chart: { type: 'line' },
  title: { text: 'Simple chart' },
  xAxis: { categories: ['Jan', 'Feb', 'Mar', 'Apr'] },
  yAxis: { title: { text: 'Revenue' } },
  series: [
    { type: 'line', name: 'Orders', data: [29.9, 71.5, 106.4, 129.2] }
  ]
};

export function RevenueChart() {
  return <Chart highcharts={Highcharts} options={options} />;
}
```

## Features

| Feature | Supported |
| :--- | :---: |
| React 19 tested release line | ✅ |
| Highcharts 13 tested release line | ✅ |
| Standard `Highcharts.Chart` rendering | ✅ |
| `stockChart` constructor support | ✅ |
| `mapChart` and `ganttChart` constructor names | ✅ |
| Native Highcharts options object | ✅ |
| Native chart instance access through React refs | ✅ |
| `onChartReady` callback | ✅ |
| Highcharts module registration helpers | ✅ |
| Duplicate module registration guard | ✅ |
| ResizeObserver reflow support | ✅ |
| Window resize reflow fallback | ✅ |
| Controlled `chart.update(...)` arguments | ✅ |
| Immutable recreation mode | ✅ |
| Series-data update mode for realtime charts | ✅ |
| Option callbacks stay native Highcharts callbacks | ✅ |
| Static examples for common chart types | ✅ |
| Realtime chart demo coverage | ✅ |
| Versioned docs builds per React line | ✅ |

## Security

See the [security policy](https://github.com/alexandroit/react-highcharts/blob/main/SECURITY.md) for supported release lines and private vulnerability reporting.

Keep framework peers and application dependencies patched. Dependency audits cover known advisories; they do not establish that an application is secure.

## API Surface

| Prop | Type | Notes |
| :--- | :--- | :--- |
| `highcharts` | `typeof Highcharts` | Required. Pass the Highcharts instance or bundle your application wants to use. |
| `options` | `Highcharts.Options` | Required. Passed into the selected Highcharts constructor. |
| `constructorType` | `'chart' \| 'stockChart' \| 'mapChart' \| 'ganttChart'` | Defaults to `'chart'`. |
| `onChartReady` | `(chart: Highcharts.Chart) => void` | Called after the chart is created. |
| `allowChartUpdate` | `boolean` | Defaults to `true`. Set to `false` for manual native updates. |
| `immutable` | `boolean` | Recreates the chart instead of calling `chart.update(...)`. |
| `updateMode` | `'options' \| 'series-data'` | Defaults to `'options'`. Use `'series-data'` for stable realtime series. |
| `updateArgs` | `[redraw, oneToOne, animation]` | Forwarded to `chart.update(...)` in options mode. |
| `containerProps` | `React.HTMLAttributes<HTMLDivElement>` | Props and styles for the chart container. |

| Export | Type | Notes |
| :--- | :--- | :--- |
| `Chart` | React component | Main wrapper component. |
| `ChartHandle` | Type | Ref shape with `chart` and `container`. |
| `ChartProps` | Type | Component prop type. |
| `ConstructorType` | Type | Supported constructor string union. |
| `exposeHighchartsGlobals` | Function | Assigns `Highcharts` and `_Highcharts` on `globalThis` for modules that expect globals. |
| `initHighchartsModules` | Function | Applies Highcharts modules once per Highcharts instance. |
| `HighchartsModuleFactory` | Type | Accepted module factory shape. |
### Constructor Switch

Use `constructorType` when the chart should be created with another Highcharts constructor.

```tsx
import Highcharts from 'highcharts/highstock';
import { Chart } from '@stackline/react-highcharts';

const stockOptions: Highcharts.Options = {
  rangeSelector: { selected: 1 },
  title: { text: 'BNBUSDT candles' },
  series: [
    {
      type: 'candlestick',
      name: 'BNBUSDT',
      data: []
    }
  ]
};

export function CandleChart() {
  return (
    <Chart
      highcharts={Highcharts}
      constructorType="stockChart"
      options={stockOptions}
    />
  );
}
```

Common constructor values:

| Constructor | Usage |
| :--- | :--- |
| `chart` | Default Highcharts charts. |
| `stockChart` | Highstock timelines, candlesticks, ranges, and financial charts. |
| `mapChart` | Highmaps-style charts when the matching Highcharts build is registered. |
| `ganttChart` | Gantt-style charts when the matching Highcharts build is registered. |


### Highcharts Modules

Register Highcharts modules once at application startup. The helper accepts both direct module factories and ESM default exports.

```tsx
import Highcharts from 'highcharts/highstock';
import {
  Chart,
  exposeHighchartsGlobals,
  initHighchartsModules
} from '@stackline/react-highcharts';

exposeHighchartsGlobals(Highcharts);

const [moreModule, heatmapModule, treemapModule, solidGaugeModule] = await Promise.all([
  import('highcharts/highcharts-more.js'),
  import('highcharts/modules/heatmap.js'),
  import('highcharts/modules/treemap.js'),
  import('highcharts/modules/solid-gauge.js')
]);

initHighchartsModules(
  Highcharts,
  moreModule,
  heatmapModule,
  treemapModule,
  solidGaugeModule
);
```

The live test matrix covers examples for line, spline, area, areaspline, column, bar, stacked column, pie, donut, scatter, bubble, combination, polar, gauge, solid gauge, heatmap, treemap, funnel, 3D column, StockChart, map-like charts, renko, point-and-figure, and no-data states.


### Events

Highcharts event callbacks stay inside the native options object, so existing Highcharts knowledge transfers directly.

```tsx
const options: Highcharts.Options = {
  chart: {
    zoomType: 'xy',
    events: {
      selection(event) {
        console.log('selection', event.xAxis?.[0]);
      }
    }
  },
  plotOptions: {
    series: {
      allowPointSelect: true,
      events: {
        mouseOver() {
          console.log('series hover', this.name);
        }
      },
      point: {
        events: {
          select() {
            console.log('point selected', this.category, this.y);
          }
        }
      }
    }
  },
  series: [{ type: 'column', name: 'Visits', data: [13, 18, 42, 68] }]
};
```


### Native Chart Instance

Use a React ref when your application needs the real `Highcharts.Chart` instance.

```tsx
import { useRef } from 'react';
import Highcharts from 'highcharts';
import { Chart, type ChartHandle } from '@stackline/react-highcharts';

export function ImperativeChart() {
  const chartRef = useRef<ChartHandle>(null);

  return (
    <>
      <button
        type="button"
        onClick={() => chartRef.current?.chart?.series[0]?.addPoint(42)}
      >
        Add point
      </button>

      <Chart
        ref={chartRef}
        highcharts={Highcharts}
        options={{
          title: { text: 'Native instance access' },
          series: [{ type: 'spline', data: [2, 3, 5, 8, 13] }]
        }}
      />
    </>
  );
}
```


### Dynamic Updates

By default, the wrapper calls `chart.update(options, ...updateArgs)` when the options prop changes.

For realtime data feeds, `updateMode="series-data"` updates existing series data when the chart shape is stable. This avoids full object recreation and reduces visual blinking in live charts.

```tsx
<Chart
  highcharts={Highcharts}
  options={liveOptions}
  updateMode="series-data"
  updateArgs={[true, true, false]}
/>
```

Use `immutable` when you intentionally want a full chart recreation:

```tsx
<Chart highcharts={Highcharts} options={options} immutable />
```

Use `allowChartUpdate={false}` when a chart should be created once and then controlled manually through the native chart instance:

```tsx
<Chart
  ref={chartRef}
  highcharts={Highcharts}
  options={snapshotOptions}
  allowChartUpdate={false}
/>
```


### Common Chart Types

The wrapper does not limit chart types. If Highcharts supports it and the required module is registered, pass the native options object.

| Chart family | Examples |
| :--- | :--- |
| Core charts | line, spline, area, areaspline, column, bar, pie, donut |
| Analytics charts | scatter, bubble, heatmap, treemap, funnel, solid gauge |
| Financial charts | StockChart, candlestick, HLC, OHLC, renko, point-and-figure |
| Advanced modules | 3D column, packed bubble, dependency wheel, network graph, sunburst |
| Map-like modules | map-style charts when the matching Highcharts map build is registered |


### Wrapper Capabilities

| Capability | API |
| :--- | :--- |
| Options API | `<Chart highcharts={Highcharts} options={options} />` |
| Constructor switch | `constructorType="stockChart"` |
| Native ref access | `chartRef.current?.chart` |
| Controlled updates | `allowChartUpdate`, `immutable`, `updateArgs` |
| Realtime series updates | `updateMode="series-data"` |
| Module registration | `initHighchartsModules(Highcharts, ...modules)` |
| Module globals | `exposeHighchartsGlobals(Highcharts)` |
| Responsive reflow | `ResizeObserver` plus window resize fallback |

<a id="run-locally"></a>
<a id="development"></a>

## Local Development

```bash
git clone https://github.com/alexandroit/react-highcharts.git
cd react-highcharts
npm ci
npm run check
```

## Consumer Smoke Test

`npm run check` builds the library and checks its public package contents and existing behavior. Run `npm run test:consumer` for the existing installed-consumer matrix.

## Release Checklist

- Run `npm ci`, `npm run check`, and the applicable browser or consumer checks.
- Review `npm audit` and `npm audit --omit=dev` separately.
- Review the packed README, declarations, exports, license, and compatibility metadata.
- Publish through the [GitHub Actions workflow](https://github.com/alexandroit/react-highcharts/actions/workflows/publish.yml) using the tested artifact's SHA-512 digest.
- Verify the exact npm tarball, version, and GitHub provenance after publication; never replace a published version.

## Changelog

### 19.1.0

- Validated React 19.2.8, React DOM 19.2.8, and Highcharts 13.0.1 without changing the wrapper API.
- Fixed imperative refs so `chart` and `container` always expose the live instances.
- Fixed consecutive `immutable` updates so every requested recreation is applied.
- Added lifecycle, module, package, browser, and audit release contracts.
- Updated the React 19 demo to Vite 8.2.1 and explicit Highcharts 13 data-sorting registration.

### 19.0.0

- Added the maintained React 19 package line with React 19.2.7 validation.
- Kept Highcharts 12.6.0 as the tested compatibility ceiling for this line.
- Reused the corrected modern live matrix from the React 18 release: realtime charts, static chart families, module-heavy examples, and stable live updates without blinking.
- Kept README media on the public Stackline assets host.

### 18.0.0

- Added the maintained React 18 package line with React 18.3.1 validation.
- Kept Highcharts 12.6.0 as the tested compatibility ceiling for this line.
- Reused the corrected modern live matrix from the React 17 release: realtime charts, static chart families, module-heavy examples, and no blink/recreate behavior for stable live updates.
- Updated the README image to the public Stackline assets host.

### 17.0.0

- Updated the library line for React 17.0.2.
- Added the React 17 live app with full Highcharts example coverage.
- Aligned the React live template with the Angular 21 Highcharts documentation style.
- Updated the demo to use Highcharts 12.6.0 with the latest stable compatible module set.
- Improved responsive chart behavior by reflowing on container resize.
- Added `updateMode="series-data"` for live charts that should update existing series instead of recreating the chart.
- Added a small chart DOM sanitizer for invalid SVG `visibility="NaN"` output from derived Highcharts modules.

## License

The React wrapper in this repository is released under the [MIT License](https://github.com/alexandroit/react-highcharts/blob/main/LICENSE).

Highcharts is a separate peer dependency and is not distributed under this repository's MIT license. Review the [Highcharts licensing terms](https://www.highcharts.com/license) for your application.

## Credits and original authors

- Copyright (c) 2026 Alexandro Marques.
- Stackline maintenance: [Alexandro Paixao Marques](https://www.linkedin.com/in/aleinfo/) and [Stackline contributors](https://github.com/alexandroit).

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

## Community and Links

- [Stackline website](https://alexandro.net/)
- [GitHub projects](https://github.com/alexandroit)
- [npm packages](https://www.npmjs.com/~alex360qc)
- [Reddit community — r/Stackline](https://www.reddit.com/r/Stackline/)
- [Maintainer LinkedIn](https://www.linkedin.com/in/aleinfo/)

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.