API

🚨 This documentation is for Version 3.0.0, which is currently in beta and is a work-in-progress. For now, please refer to the examples for any missing documentation.

Memoize your Props!

The React Charts <Chart> component has a few options that need to be stable or memoized using either React.useMemo or React.useCallback. Using an unstable option incorrectly shouldn't severly break any basic functionality, but could results in infinite change-detection loops in your app or at the very least, your charts will be severly non-performant. If an option says it needs to be stable, it's not kidding around!

Data Model

React Charts uses a data shape based on arrays of series and nested arrays of datums in those series.

1 const data = [
2   {
3     label: 'Purchases',
4     data: [
5       {
6         date: new Date(),
7         stars: 299320,
8       },
9       // ...etc
10     ],
11   },
12 ]

Visualization data can come in practically any shape and size, so memoization of data into this shape is almost always necessary.

1 const data = React.useMemo(
2   () => [
3     {
4       label: 'Series 1',
5       data: [
6         // ...
7       ],
8     },
9     {
10       label: 'Series 2',
11       data: [
12         // ...
13       ],
14     },
15     {
16       label: 'Series 3',
17       data: [
18         // ...
19       ],
20     },
21   ],
22   []
23 )

The individual datums in a series' data array can be anything you want! Just remember that most of the types for React Charts will require you to pass the type of your Datums as the first generic type to work correctly.

Axes

React Charts use axes to configure a fair amount of the charts. Axes handle many things like:

• Accessing chart values from your series' Datums
• Optionally positioning your axis on the grid
• Optionally configuring the scale type for your axis
• Optionally configuring the element type for series that are tied to your axis

To date, we have the following scale types available:

• linear - A continuous axis used for plotting numerical data on an evenly distributed scale. Works well both as a primary and secondary axis.
• band - A banded axis commonly used to plot categories or ordinal information. Works well as the primary axis for bar charts with ordinal domains.
• time - A continuous axis used for plotting UTC Dates on an evenly distributed scale. Works well as a primary axis.
• timeLocal - Similar to the time scale, but uses localized Date objects instead of UTC. Works well as a primary axis.
• log - A continuous axis used for plotting numerical data on a logarithmically distributed scale. Works well as a secondary axis

Axes are a required component of a React Chart. Both a primaryAxis and at least one axis vis secondaryAxes must be configured.

1 import { Chart } from 'react-charts'
2 
3 type MyDatum = { date: Date, stars: number }
4 
5 function MyChart() {
6   const data = [
7     {
8       label: 'React Charts',
9       data: [
10         {
11           date: new Date(),
12           stars: 23467238,
13         },
14       ],
15     },
16   ]
17 
18   const primaryAxis = React.useMemo(
19     (): AxisOptions<MyDatum> => ({
20       getValue: datum => datum.date,
21     }),
22     []
23   )
24 
25   const secondaryAxes = React.useMemo(
26     (): AxisOptions<MyDatum>[] => [
27       {
28         getValue: datum => datum.stars,
29       },
30     ],
31     []
32   )
33 
34   return (
35     <Chart
36       options={{
37         data,
38         primaryAxis,
39         secondaryAxes,
40       }}
41     />
42   )
43 }

Secondary Axis Element Types

Secondary axes for the most part are automatic, but can be optionally configured to render their respective series using 3 different element types using the AxisOptions<TDatum>['scaleType'] property:

• line
  • 1 Line per series (optional, eg. for Bubble/Scatter charts)
  • 1 Circle per datum (optional)
• area
  • 1 Enclosed area per series
  • 1 Line per series (optional)
  • 1 Circle per datum (optional)
• bar
  • 1 Rectangle per datum

Example

1 const secondaryAxes = React.useMemo(
2   (): AxisOptions<MyDatum>[] => [
3     {
4       getValue: datum => datum.stars,
5       elementType: 'bar',
6     },
7   ],
8   []
9 )

Chart Component Props

The Chart component props can be passed in its options property object:

1 <Chart
2   options={{
3     data,
4     primaryAxis,
5     secondaryAxes,
6   }}
7 />

The data property should be an array of series, each series should be an array of objects. Each object should have two properties, by convention called primary and secondary, but it can be named as you want. One of these properties will be used as the primary axis and the other as the secondary axes.

1 const data = [
2   {
3     label: 'Series 1',
4     data: [
5       {
6         primary: '2022-02-03T00:00:00.000Z',
7         likes: 130,
8       },
9       {
10         primary: '2022-03-03T00:00:00.000Z',
11         likes: 150,
12       },
13     ],
14   },
15   {
16     label: 'Series 2',
17     data: [
18       {
19         primary: '2022-04-03T00:00:00.000Z',
20         likes: 200,
21       },
22       {
23         primary: '2022-05-03T00:00:00.000Z',
24         likes: 250,
25       },
26     ],
27   },
28 ]

The primaryAxis and secondaryAxes options, should have a prop called getValue, which is a getter function that returns the axis value for the datum. Example:

1 const primaryAxis = React.useMemo(
2   () => ({
3     getValue: (datum: { primary: string }) => datum.primary,
4   }),
5   []
6 )
7 const secondaryAxes = React.useMemo(
8   () => [
9     {
10       getValue: (datum: { likes: number }) => datum.likes,
11       elementType: 'area',
12     },
13   ],
14   []
15 )

initialHeight and initialWidth expect a number, a default value is applied for each of those, 300 and 200 respectively. It's important to mention that these options are available SSR onoly. If you'd like to have a custom height and width in the client side you may have a wrapper div that sets the width and height CSS attributes

interactionMode expect an string wich can be "primary" or "closest". It's been using for the tooltip position. By default, primary is being set.

showVoronoi expect a boolean, it's a debug option to visualize the interaction click-map that sits on top of the chart.

getSeriesOrder expect a function, this option will allows you to reorder the series if you want.

primaryCursor and secundaryCursor take the options that configure the line/rectangle that is drawn underneath your cursor when you hover over the chart. When both are used, it produces a kind of cross-hair. Both are set to true by default.

Curve Types

All element types that support lines or curves can be configured by passing any curve generator function as the AxisOptions<TDatum>['curve'] option. By default, horizontal and vertical series default to using monotoneX and monotoneY curves, respectively. More information can be found at d3-shape curves

API

Coming Soon! Feel free to consult the examples or refer to the exported types in your favorite IDE for now.