Chart interactions

Use cases

Chart interactions enable additional possibilities for end users to interact with the data plotted within the chart area. The interactive options currently supported within the TimeseriesChart, the HistogramChart and the XYChart are zoom, pan, and select.

To incorporate these interactions, add the corresponding slot components inside the chart:

<TimeseriesChart data={data}>
  <TimeseriesChart.Zoom />
  <TimeseriesChart.Pan />
  <TimeseriesChart.Select />
</TimeseriesChart>

For the XYChart, every X-axis can opt-in or opt-out for enabling these interactions by specifying two props: disableZoom and disablePan (for more information, see Zoom and Pan).

Chart interactions can be triggered using keyboard shortcuts or by using the chart toolbar. The toolbar is enabled by default. To customize the toolbar (e.g., hide it or change its placement), add the toolbar slot to the chart: <TimeseriesChart.Toolbar />, <HistogramChart.Toolbar />, or <XYChart.Toolbar />.

Explore

The explore functionality is the default mode, and it allows you to inspect the data within the chart. It allows you to select an area to zoom along the X-axis. This mode is enabled by default and works in combination with the Zoom and Select slots.

You can optionally trigger this mode from the keyboard by pressing E while the chart has focus.

Pan

Once a user has zoomed into the plotted data on a chart, panning can optionally be enabled. Panning allows users to navigate left and right along the X-axis whilst in a zoomed-in state. To enable this functionality, add the Pan slot to the chart:

<TimeseriesChart data={data}>
  <TimeseriesChart.Pan />
</TimeseriesChart>

This interaction is enabled by default in XYChart, TimeseriesChart and HistogramChart

You can optionally trigger this mode from the keyboard by pressing P while the chart has focus.

Once you have triggered this mode:

• Pressing ← (Left Arrow) will pan to the left. You can also press Shift to increase the speed of pan movement.
• Pressing → (Right Arrow) will pan to the right. You can also press Shift to increase the speed of pan movement.

Select

The select functionality allows users to select a specific area in the chart. Selection can be used to display detailed information about data points inside the selected area and/or to zoom in to the selected area. The select interaction is enabled by default for XYChart, TimeseriesChart and HistogramChart. You can explicitly add it to customize behavior:

Select can be triggered by clicking and dragging on the chart area. To zoom in on the selected area, press Enter.

<TimeseriesChart data={data}>
  <TimeseriesChart.Select
    actions={(selectedSeries) => (
      <ChartSeriesAction>
        <ChartSeriesAction.Item onSelect={() => console.log(selectedSeries)}>
          Custom action
        </ChartSeriesAction.Item>
      </ChartSeriesAction>
    )}
  />
</TimeseriesChart>

Upon selecting an area, the chart will display a tooltip with the selected area's start and end timestamps, duration of the area, and amount of data points and series. The tooltip can be dismissed by pressing Esc. The selected area can include custom actions and intents. You can define custom actions using the actions prop on the Select slot.

Zoom

The zoom functionality allows users to zoom in to the chart's plotted data by a fixed point along the X-axis. The chart supports zoom in (incremental) and zoom out (decremental) actions.

To enable zoom interactions, add the Zoom slot to the chart:

<TimeseriesChart data={data}>
  <TimeseriesChart.Zoom />
</TimeseriesChart>

This interaction is enabled by default.

You can optionally zoom in/out different ways by first focusing the chart:

• Pressing Cmd (Ctrl in Windows) + the mouse wheel, will generate a zoom in/out trigger.
• Pressing Cmd + ↑ (Up Arrow) will zoom in.
• Pressing Cmd + ↓ (Down Arrow) will zoom out.
• Pressing Cmd + click will zoom in.
• Pressing Cmd + pressing Shift + click will zoom out.
• Pressing Cmd + clicking and dragging draws a zoom area and zooms in on mouse up.

Reset

Reset will restore the chart to its initial state.

You can optionally trigger this action from the keyboard by pressing R while the chart has focus.

• Double-clicking on any part of the chart will trigger a reset.

The following charts have all interactions enabled (explore, zoom, pan, select with custom actions).

CodeSandbox

CodeSandbox

CodeSandbox

It's also possible to programmatically trigger all the previously described interactions by calling their methods on the TimeseriesChart instance reference. The available options are: exploreMode, zoomMode, panMode, zoomIn, zoomOut and reset.

CodeSandbox

CodeSandbox

CodeSandbox