Chart interactions

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.

Zoom, pan, and select are enabled by default. Add the corresponding slot only to disable an interaction or, for Select, to add custom actions — e.g. <TimeseriesChart.Zoom disabled />, <XYChart.Pan disabled />, <HistogramChart.Select actions={...} />.

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

Panning allows users to navigate left and right along the X-axis whilst in a zoomed-in state. Pan is enabled by default. To disable it, add the slot for your chart: <TimeseriesChart.Pan disabled />, <HistogramChart.Pan disabled />, or <XYChart.Pan disabled />.

Regardless of the active mode, you can also pan by clicking the arrow buttons on the respective X-axis, or by clicking and dragging the X-axis directly.

Pan can be activated permanently by pressing P or via the toolbar, or temporarily by holding Alt (Option on Mac) while in any other mode. Temporary mode takes precedence over the active mode.

Once in pan mode (permanent or temporary):

• Clicking and dragging on the chart pans left/right. You can also use the middle mouse button.
• The mouse wheel pans left/right on the chart.
• Pressing ArrowLeft pans to the left. Hold Shift to increase speed.
• Pressing ArrowRight pans to the right. Hold Shift to increase speed.

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.

Disabling selection

To prevent users from drawing a selection area, pass the disabled prop to the Select slot. This is useful when the chart is embedded in a read-only context or when selection is not relevant to the current view. Zoom and pan interactions remain fully functional when selection is disabled.

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. Zoom is enabled by default. To disable it, add the slot for your chart: <TimeseriesChart.Zoom disabled />, <HistogramChart.Zoom disabled />, or <XYChart.Zoom disabled />.

Zoom can be activated permanently by pressing Z or via the toolbar, or temporarily by holding Cmd (Ctrl on Windows) while in any other mode. Temporary mode takes precedence over the active mode.

Once in zoom mode (permanent or temporary):

• The mouse wheel zooms in/out.
• Clicking zooms in. Hold Shift to zoom out.
• Clicking and dragging draws a zoom area and zooms in on mouse up.
• Pressing ↑ (Up Arrow) zooms in. Pressing ↓ (Down Arrow) zooms out.

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

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.