Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/highcharts/highcharts-react

The official Highcharts supported wrapper for React
https://github.com/highcharts/highcharts-react

Last synced: 27 days ago
JSON representation

The official Highcharts supported wrapper for React

Awesome Lists containing this project

README

        

# Highcharts React
Official minimal [Highcharts](https://www.highcharts.com/) integration for React.

## Table of Contents
1. [Getting started](#getting-started)
1. [General prerequisites](#general-prerequisites)
2. [Installing](#installing)
3. [Using](#using)
1. [Basic usage example](#basic-usage-example)
2. [Highcharts with NextJS](#highcharts-with-nextjs)
3. [Highcharts with TypeScript](#highcharts-with-typescript)
4. [Optimal way to update](#optimal-way-to-update)
2. [Options details](#options-details)
3. [Example with custom chart component](#example-with-custom-chart-component)
4. [Get repository](#get-repository)
5. [Examples](#examples)
6. [Tests](#tests)
7. [Changelog](#changelog)
8. [FAQ](#faq)
1. [Where to look for help?](#where-to-look-for-help)
2. [Why highcharts-react-official and not highcharts-react is used?](#why-highcharts-react-official-and-not-highcharts-react-is-used)
3. [How to get a chart instance?](#how-to-get-a-chart-instance)
4. [How to add a module?](#how-to-add-a-module)
5. [How to add React component to a chart's element?](#how-to-add-react-component-to-a-charts-element)
6. [Why Highcharts mutates my data?](#why-highcharts-mutates-my-data)

## Getting Started

### General prerequisites

Make sure you have **node**, **NPM** and **React** up to date.
Tested and required versions:

* `node` 8.11.3+
* `npm` 6.4.1+ or similar package manager

This integration also requires highcharts and react packages with the following versions installed in your project:

For version **2.x.x** :

* `react` 16.4+
* `highcharts` 5.0.0+

For version **3.x.x** :

* `react` 16.8+
* `highcharts` 6.0.0+

### Installing

Get the package from NPM in your React app:

```bash
npm install highcharts-react-official
```

If Highcharts is not already installed, get the package with Highcharts:

```bash
npm install highcharts highcharts-react-official
```

### Using

#### Basic usage example

Import into your React project and render a chart:

```jsx
import React from 'react'
import { render } from 'react-dom'
import Highcharts from 'highcharts'
import HighchartsReact from 'highcharts-react-official'

const options = {
title: {
text: 'My chart'
},
series: [{
data: [1, 2, 3]
}]
}

const App = () =>



render(, document.getElementById('root'))
```

### Highcharts with TypeScript

Live example: https://stackblitz.com/edit/react-starter-typescript-cfcznt

```tsx
import React, { useRef } from 'react';
import * as Highcharts from 'highcharts';
import { HighchartsReact } from 'highcharts-react-official';

// The integration exports only a default component that at the same time is a
// namespace for the related Props interface (HighchartsReact.Props) and
// RefObject interface (HighchartsReact.RefObject). All other interfaces
// like Options come from the Highcharts module itself.

const options: Highcharts.Options = {
title: {
text: 'My chart'
},
series: [{
type: 'line',
data: [1, 2, 3]
}]
};

const App = (props: HighchartsReact.Props) => {
const chartComponentRef = useRef(null);

return (

);
};
// Render your App component into the #root element of the document.
ReactDOM.render(, document.getElementById('root'));
```

Since version 3.2.1 it is also possible to import types for `props` and `ref` independently:

```tsx
import HighchartsReact, { HighchartsReactRefObject, HighchartsReactProps } from 'highcharts-react-official';
```

### Highcharts with NextJS

Next.js executes code twice - on server-side and then client-side. First run is done in an environment that lacks `window` and causes Highcharts to be loaded, but not initialized. Easy fix is to place all modules inits in a `if` checking if Highcharts is an object or a function. It should be an object for modules initialization to work without any errors, so code like below is an easy fix:

```jsx
import React from 'react'
import Highcharts from 'highcharts'
import HighchartsExporting from 'highcharts/modules/exporting'
import HighchartsReact from 'highcharts-react-official'

if (typeof Highcharts === 'object') {
HighchartsExporting(Highcharts)
}

...
```

This is a know issue with NextJS and is covered here: https://github.com/vercel/next.js/issues/5354

### Optimal way to update

A good practice is to keep all chart options in the state. When `setState` is called, the options are overwritten and only the new ones are passed to the `chart.update` method.

**Live example:** https://stackblitz.com/edit/react-hketvd?file=index.js

**Optimal way to update with React Hooks:** https://stackblitz.com/edit/react-nwseym?file=index.js

```jsx
import React, { Component } from 'react';
import { render } from 'react-dom';
import HighchartsReact from 'highcharts-react-official';
import Highcharts from 'highcharts';

class LineChart extends Component {
constructor(props) {
super(props);

this.state = {
// To avoid unnecessary update keep all options in the state.
chartOptions: {
xAxis: {
categories: ['A', 'B', 'C'],
},
series: [
{ data: [1, 2, 3] }
],
plotOptions: {
series: {
point: {
events: {
mouseOver: this.setHoverData.bind(this)
}
}
}
}
},
hoverData: null
};
}

setHoverData = (e) => {
// The chart is not updated because `chartOptions` has not changed.
this.setState({ hoverData: e.target.category })
}

updateSeries = () => {
// The chart is updated only with new options.
this.setState({
chartOptions: {
series: [
{ data: [Math.random() * 5, 2, 1]}
]
}
});
}

render() {
const { chartOptions, hoverData } = this.state;

return (



Hovering over {hoverData}


Update Series

)
}
}

render(, document.getElementById('root'));
```

## Options details

Available options with example values:

```jsx

```

| Parameter | Type | Required | Defaults | Description |
| --------- | :----: | :--------: | :--------: | ----------- |
| `options` | Object | yes | - | Highcharts chart configuration object. Please refer to the Highcharts [API documentation](https://api.highcharts.com/highcharts/). |
| `highcharts` | Object | yes | - | Used to pass the Highcharts instance after modules are initialized. If not set the component will try to get the Highcharts from window. |
| `constructorType` | String | no | `'chart'` | String for [constructor method](https://www.highcharts.com/docs/getting-started/your-first-chart). Official constructors:
- `'chart'` for Highcharts charts
- `'stockChart'` for Highstock charts
- `'mapChart'` for Highmaps charts
- `'ganttChart'` for Gantt charts|
| `allowChartUpdate` | Boolean | no | `true` | This integration uses `chart.update()` method to apply new options to the chart when changing the parent component. This option allow to turn off the updating. |
| `immutable` | Boolean | no | `false` | Reinitialises the chart on prop update (as oppose to `chart.update()`) - useful in some cases but slower than a regular update.|
| `updateArgs` | Array | no | `[true, true, true]` | Array of `update()`'s function optional arguments. Parameters should be defined in the same order like in native Highcharts function: `[redraw, oneToOne, animation]`. [Here](https://api.highcharts.com/class-reference/Highcharts.Chart#update) is a more specific description of the parameters.|
| `containerProps` | Object | no | - | The props object passed to the chart container in `React.createElement` method. Useful for adding styles or class.|
| `callback` | Function | no | - | A callback function for the created chart. First argument for the function will hold the created `chart`. Default `this` in the function points to the `chart`. This option is optional. |

## Example with custom chart component

Create custom component `./components/MyStockChart.jsx`:

```jsx
import React from 'react'
import Highcharts from 'highcharts/highstock'
import HighchartsReact from 'highcharts-react-official'

const options = {
title: {
text: 'My stock chart'
},
series: [{
data: [1, 2, 3]
}]
}

const MyStockChart = () =>

export default MyStockChart
```

Render your custom chart component like below:

```jsx
import React from 'react'
import { render } from 'react-dom'
import MyStockChart from './components/MyStockChart.jsx'

const App = () =>



render(, document.getElementById('root'))
```

## Get repository

Clone github repository and install dependencies:

```bash
git clone https://github.com/highcharts/highcharts-react
cd highcharts-react
npm install
```

Examples and tests require Highcharts library, don't forget to:

```bash
npm install highcharts
```

## Examples

There are several interesting examples in the demo folder that use all available constructors and several modules.

Bundle these with:

```bash
npm run build-demo
```

Demo is located under demo/index.html

Live example: https://stackblitz.com/edit/react-4ded5d?file=index.js

## Tests

This integration contains tests for: testing environment, chart rendering and passing down container props.
To run tests, type:

```bash
npm run test
```

## Changelog
The changelog is available [here](https://github.com/highcharts/highcharts-react/blob/master/CHANGELOG.md).

## FAQ

### Where to look for help?

[Technical support](https://www.highcharts.com/support) will help you with Highcharts and with the integration.

If you have a bug to report or an enhancement suggestion please submit [Issues](https://github.com/highcharts/highcharts-react/issues) in this repository.

### Why highcharts-react-official and not highcharts-react is used?

The NPM package is registered as `highcharts-react-official` because `highcharts-react` was already taken.

### How to get a chart instance?

For class components and version prior to 3.0.0 use `React.createRef`:

```jsx
constructor(props) {
super(props)
this.chartRef = React.createRef();
}

render() {
return (

);
}
```

For functional components and version 3.0.0 and later use `useRef` hook:

```jsx
const chartComponent = useRef(null);
const [options] = useState({...});

useEffect(() => {
const chart = chartComponent.current.chart;
...
}, []);

return ;
```

Alternatively store a chart reference in a callback function:

```jsx
afterChartCreated = (chart) => {
// Highcharts creates a separate chart instance during export
if (!chart.options.chart.forExport) {
this.internalChart = chart;
}
}

componentDidMount() {
// example of use
this.internalChart.addSeries({ data: [1, 2, 3] })
}

render() {
return (


Highcharts




);
}
```

### How to add a module?

To add a module, import and initialize it:

```jsx
import Highcharts from 'highcharts'
import highchartsGantt from "highcharts/modules/gantt";
import HighchartsReact from 'highcharts-react-official'

// init the module
highchartsGantt(Highcharts);
```

alternative with `require`:

```jsx
import Highcharts from 'highcharts'
import HighchartsReact from 'highcharts-react-official'

require("highcharts/modules/variwide")(Highcharts);
```

### How to add React component to a chart's element?

By using [Portals](https://en.reactjs.org/docs/portals.html) it is possible to add a component to every HTML chart element.

Live example: https://codesandbox.io/s/1o5y7r31k3

### Why Highcharts mutates my data?

It can be confusing, since React props are read-only, but Highcharts for performance reasons mutates the original data array. This behaviour is NOT changed by our integration. You need to pass a copy of your data to the integration if you want to prevent mutations.

Issue: https://github.com/highcharts/highcharts-react/issues/326

More discussion here: https://github.com/highcharts/highcharts/issues/4259