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.

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.

import { buildChartTheme, XYChart } from '@visx/xychart';
import { TextProps as SVGTextProps } from '@visx/text/lib/Text'; // just for types

const customTheme = buildChartTheme({
  // colors
  backgroundColor: string; // used by Tooltip, Annotation
  colors: string[]; // categorical colors, mapped to series via `dataKey`s

  // labels
  svgLabelBig?: SVGTextProps;
  svgLabelSmall?: SVGTextProps;
  htmlLabel?: HTMLTextStyles;

  // lines
  xAxisLineStyles?: LineStyles;
  yAxisLineStyles?: LineStyles;
  xTickLineStyles?: LineStyles;
  yTickLineStyles?: LineStyles;
  tickLength: number;

  // grid
  gridColor: string;
  gridColorDark: string; // used for axis baseline if x/yxAxisLineStyles not set
  gridStyles?: CSSProperties;
});

() => <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:

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

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

import React from 'react';
import {
  Annotation,
  AnnotationLabel,
  AnnotationConnector,
  AnnotationCircleSubject,
  Grid,
  LineSeries,
  XYChart,
} from '@visx/xychart';

const data = [
  { x: '2020-01-01', y: 50 },
  { x: '2020-01-02', y: 10 },
  { x: '2020-01-03', y: 20 },
  { x: '2020-01-04', y: 5 },
];

const labelXOffset = -40;
const labelYOffset = -50;
const chartConfig = {
  xScale: { type: 'band' },
  yScale: { type: 'linear' },
  height: 300,
  margin: { top: 10, right: 10, bottom: 10, left: 10 },
};

export default () => (
  <XYChart {...chartConfig}>
    <Grid numTicks={3} />
    <LineSeries dataKey="line" data={data} xAccessor={d => d.x} yAccessor={d => d.y} />
    <Annotation
      dataKey="line" // use this Series's accessor functions, alternatively specify x/yAccessor here
      datum={data[2]}
      dx={labelXOffset}
      dy={labelYOffset}
    >
      {/** Text label */}
      <AnnotationLabel
        title="Title"
        subtitle="Subtitle deets"
        showAnchorLine={false}
        backgroundFill="rgba(0,150,150,0.1)"
      />
      {/** Draw circle around point */}
      <AnnotationCircleSubject />
      {/** Connect label to CircleSubject */}
      <AnnotationConnector />
    </AnimatedAnnotation>
  </XYChart>
);

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

import React, { useState } from 'react';
import { useEventEmitter, EventEmitterProvider } from '@visx/xychart';

const eventSourceId = 'optional-source-id-filter';

const EmitEvent = () => {
  const emit = useEventEmitter();
  return <button onPointerUp={event => emit('pointerup', event, eventSourceId)}>emit event</button>;
};

const SubscribeToEvent = () => {
  const [clickCount, setClickCount] = useState(0);
  const allowedEventSources = [eventSourceId];
  useEventEmitter('pointerup', () => setClickCount(clickCount + 1), allowedEventSources);

  return <div>Emitted {clickCount} events</div>;
};

export default function Example() {
  return (
    <EventEmitterProvider>
      <EmitEvent />
      <SubscribeToEvent />
    </EventEmitterProvider>
  );
}

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).

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

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

✅ No errors

// no polyfill, target browser supports ResizeObserver
() => <XYChart {...}><Tooltip /></XYChart>

// import the polyfill in the needed module, or set it on `window` object
import ResizeObserver from 'resize-observer-polyfill';
() => <XYChart {...}><Tooltip /></XYChart> // 😎

// cleanly pass polyfill to component that needs it
import ResizeObserver from 'resize-observer-polyfill';
() => (
  <XYChart {...}>
    <Tooltip resizeObserverPolyfill={ResizeObserver} />
  </XYChart>
)