npm install --save @visx/xychart react-spring

Note: react-spring is a required peerDependency for importing Animated* components.

The following Series types are currently supported and we are happy to review or consider additional Series types in the future.

| Component name | Description | Usage | | --------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | --- | | (Animated)AreaSeries | Connect data points with a <path />, with a color fill to the zero baseline | <AreaSeries /> | | (Animated)BarSeries | Render a <rect /> for each data point | <BarSeries /> | | (Animated)BarGroup | Group multiple child <BarSeries /> values together | <BarGroup><BarSeries /><BarSeries />...</BarGroup> | | (Animated)BarStack | Stack multiple child <BarSeries /> values together | <BarStack><BarSeries /><BarSeries />...</BarStack> | | | (Animated)GlyphSeries | Render a Glyph (any shape, defaults to <circle />) for each data point, e.g., a scatter plot | <GlyphSeries renderGlyph={() => ...} /> | | (Animated)LineSeries | Connect data points with a <path> | <GlyphSeries /> |

All Series have animated and non-animated variants to give you more control over your bundle size, support missing (null) data, and can be rendered vertically or horizontally.

Default lightTheme and darkTheme themes are exported from @visx/xychart and the utility buildChartTheme is exported to support easy creation of custom themes.

1import { buildChartTheme, XYChart } from '@visx/xychart';
2import { TextProps as SVGTextProps } from '@visx/text/lib/Text'; // just for types
3
4const customTheme = buildChartTheme({
5  // colors
6  backgroundColor: string; // used by Tooltip, Annotation
7  colors: string[]; // categorical colors, mapped to series via `dataKey`s
8
9  // labels
10  svgLabelBig?: SVGTextProps;
11  svgLabelSmall?: SVGTextProps;
12  htmlLabel?: HTMLTextStyles;
13
14  // lines
15  xAxisLineStyles?: LineStyles;
16  yAxisLineStyles?: LineStyles;
17  xTickLineStyles?: LineStyles;
18  yTickLineStyles?: LineStyles;
19  tickLength: number;
20
21  // grid
22  gridColor: string;
23  gridColorDark: string; // used for axis baseline if x/yxAxisLineStyles not set
24  gridStyles?: CSSProperties;
25});
26
27() => <XYChart theme={customTheme} />

@visx/tooltip Tooltips are integrated into @visx/xychart, and should be rendered as a child of XYChart (or a child where TooltipContext is provided).

Tooltip positioning is handled by the Tooltip itself, based on TooltipContext. Tooltip is rendered inside a Portal, avoiding clipping by parent DOM elements with higher z-index contexts. See the API below for a full list of props to support additional behavior, such as snapping to data point positions and rendering cross-hairs.

Tooltip content is controlled by the specified prop.renderTooltip which has access to:

• tooltipData.nearestDatum – the globally closest Datum, across all Series's dataKeys
• tooltipData.datumByKey – the closest Datum for each Series's dataKey; this enables "shared tooltips" where you can render the nearest data point for each Series.
• a shared colorScale which maps Series's dataKeys to theme colors

The following PointerEvents (handling both MouseEvents and TouchEvents) are currently supported. They may be set on individual Series components (e.g., <BarSeries onPointerMove={() => ...} />), or at the chart level (e.g., <XYChart onPointerMove={() => {}} />) in which case they are invoked once for every *Series. To disable event emitting for any Series set <*Series enableEvents=false />. The onFocus/onBlur handlers enable you to make your chart events and Tooltips accessible via keyboard interaction. Note that the current implementation requires your target browser to support the SVG 2.0 spec for tabIndex on SVG elements.

Below, HandlerParms has the following type signature:

1type EventHandlerParams<Datum> = {
2  datum: Datum; // nearest Datum to event, for Series with `dataKey=key`
3  distanceX: number; // x distance between event and Datum, in px
4  distanceY;: number; // y distance between event and Datum, in px
5  event: React.PointerEvent | React.FocusEvent; // the event
6  index: number; // index of Datum in Series `data` array
7  key: string; // `dataKey` of Series to which `Datum` belongs
8  svgPoint: { x: number; y: number }; // event position in svg-coordinates
9};

Composable @visx/annotations annotations are integrated into @visx/xychart and use its theme and dimension context. These components allow for annotation of individual points using AnnotationCircleSubject, or x- or y-thresholds using AnnotationLineSubject.

CodeSandbox

1import React from 'react';
2import {
3  Annotation,
4  AnnotationLabel,
5  AnnotationConnector,
6  AnnotationCircleSubject,
7  Grid,
8  LineSeries,
9  XYChart,
10} from '@visx/xychart';
11
12const data = [
13  { x: '2020-01-01', y: 50 },
14  { x: '2020-01-02', y: 10 },
15  { x: '2020-01-03', y: 20 },
16  { x: '2020-01-04', y: 5 },
17];
18
19const labelXOffset = -40;
20const labelYOffset = -50;
21const chartConfig = {
22  xScale: { type: 'band' },
23  yScale: { type: 'linear' },
24  height: 300,
25  margin: { top: 10, right: 10, bottom: 10, left: 10 },
26};
27
28export default () => (
29  <XYChart {...chartConfig}>
30    <Grid numTicks={3} />
31    <LineSeries dataKey="line" data={data} xAccessor={d => d.x} yAccessor={d => d.y} />
32    <Annotation
33      dataKey="line" // use this Series's accessor functions, alternatively specify x/yAccessor here
34      datum={data[2]}
35      dx={labelXOffset}
36      dy={labelYOffset}
37    >
38      {/** Text label */}
39      <AnnotationLabel
40        title="Title"
41        subtitle="Subtitle deets"
42        showAnchorLine={false}
43        backgroundFill="rgba(0,150,150,0.1)"
44      />
45      {/** Draw circle around point */}
46      <AnnotationCircleSubject />
47      {/** Connect label to CircleSubject */}
48      <AnnotationConnector />
49    </AnimatedAnnotation>
50  </XYChart>
51);

❌ Error: This browser does not support ResizeObserver out of the box

1// no polyfill, no browser support
2() => <XYChart {...} />
3() => <XYChart {...}><Tooltip /></XYChart>
4

✅ No errors

1// no polyfill, target browser supports ResizeObserver
2() => <XYChart {...} />
3() => <XYChart {...}><Tooltip /></XYChart>
4
5// import the polyfill in the needed module, or set it on `window` object
6import ResizeObserver from 'resize-observer-polyfill';
7() => <XYChart {...}><Tooltip /></XYChart> // 😎
8
9// cleanly pass polyfill to component that needs it
10import ResizeObserver from 'resize-observer-polyfill';
11() => (
12  <XYChart resizeObserverPolyfill={ResizeObserver} {...}>
13    <Tooltip />
14  </XYChart>
15)

XYChart is implemented using modularized React.context layers for scales, canvas dimensions, data, events, and tooltips which enables more advanced usage than many other chart-level abstractions.

By default XYChart renders all context providers if a given context is not available, but you can share context across multiple XYCharts to implement functionality such as linked tooltips, shared themes, or shared data.

• ThemeProvider + custom theme chart background example
• DataProvider/EventEmitterProvider example of linked tooltips / small multiples
• TooltipProvider example of programmatic + keyboard tooltip triggering

This context provides chart canvas dimensions (width, height, and margin), x/y/color scales, and a data registry. The data registry includes data from all child *Series, and x/y/color scales are updated accordingly accounting for canvas dimensions.

This context provides an XYChart theme, its used by all visual elements that compose a chart, and can be used to render custom visual elements that are on theme.

This context provides an event publishing / subscription object which can be used via the useEventEmitter hook. Series and XYChart events, including tooltip updates, are emitted and handled with through this context.

CodeSandbox

1import React, { useState } from 'react';
2import { useEventEmitter, EventEmitterProvider } from '@visx/xychart';
3
4const eventSourceId = 'optional-source-id-filter';
5
6const EmitEvent = () => {
7  const emit = useEventEmitter();
8  return (
9    <button onPointerUp={(event) => emit('pointerup', event, eventSourceId)}>emit event</button>
10  );
11};
12
13const SubscribeToEvent = () => {
14  const [clickCount, setClickCount] = useState(0);
15  const allowedEventSources = [eventSourceId];
16  useEventEmitter('pointerup', () => setClickCount(clickCount + 1), allowedEventSources);
17
18  return <div>Emitted {clickCount} events</div>;
19};
20
21export default function Example() {
22  return (
23    <EventEmitterProvider>
24      <EmitEvent />
25      <SubscribeToEvent />
26    </EventEmitterProvider>
27  );
28}

This context provides access to @visx/tooltips useTooltip state, including whether the tooltip is visible (tooltipOpen), tooltlip position (tooltipLeft, tooltipTop), tooltipData: { nearestDatum, datumByKey } described above, and functions to update context (hideTooltip, showTooltip, and updateTooltip).