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 Query will require you to pass the type of your Datums as the first generic type to work correctly.

Axes

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

• Accessing chart values from your series' Datums
• Optionally positioning your axis on the grid
• Optionsally configuring the scale type for your axis
• Optionsally 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 )

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.