Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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
- Host: GitHub
- URL: https://github.com/highcharts/highcharts-react
- Owner: highcharts
- License: other
- Created: 2017-09-26T16:13:41.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-08-20T10:49:17.000Z (3 months ago)
- Last Synced: 2024-10-02T00:42:25.781Z (about 1 month ago)
- Language: JavaScript
- Size: 796 KB
- Stars: 1,063
- Watchers: 24
- Forks: 108
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
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 managerThis 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