Charts - Tooltip

Tooltip provides extra data on charts item.

In all charts components, you can pass props to the tooltip by using tooltip={{...}}. If you are using composition, you can add the <ChartsTooltip /> component and pass props directly.

Tooltip trigger

The tooltip can be triggered by two kinds of events:

• 'item'—when the user's mouse hovers over an item on the chart, the tooltip will display data about this specific item.
• 'axis'—the user's mouse position is associated with a value of the x-axis. The tooltip will display data about all series at this specific x value.
• 'none'—disable the tooltip.

Highlights

Highlighting axis

You can highlight data based on mouse position. By default, those highlights are lines, but it can also be a vertical band if your x-axis use scaleType: 'band'.

On the chart, to customize this behavior, you can use:

axisHighlight={{
  x: 'line', // Or 'none', or 'band'
  y: 'line', // Or 'none'
}}

Highlighting series

In parallel with the tooltip, you can highlight and fade elements.

This kind of interaction is controlled by series properties highlightScope which contains two options:

• highlighted Indicates which item to highlight. Its value can be
  • 'none' Do nothing (default one).
  • 'item' Only highlight the item itself.
  • 'series' Highlight all items of the series.
• faded Indicates which item to fade (if they are not already highlighted). Its value can be
  • 'none' Do nothing (default one).
  • 'series' Fade all the items of the series.
  • 'global' Fade all the items of the chart.

Controlled Highlight

The highlight can be controlled by the user when they set highlightedItem and onHighlightChange.

You can set the highlightedItem value based on inputs, and sync it when the user hover over an item themselves.

Synchronizing Highlights

Having a controlled highlight allows you to control it in multiple charts at the same time. You just need to ensure that the series have the same ids and the data is in the same order.

Customization

Formatting

The format of data rendered in the tooltip can be modified thanks to the series valueFormatter property. The same can be applied to x values when a tooltip is triggered by the 'axis'.

Here is a demo with:

• The time axis is formatted to only show the year
• The number values are formatted in U.S. Dollars.

Advanced formatting

The series valueFormatter provides a context as its second argument containing a dataIndex property which you can use to calculate other data-related values.

In the demo below you can notice we use dataIndex to add each team's rank in the tooltip.

Axis formatter

To modify how data is displayed in the axis use the valueFormatter property.

Its second argument is a context that provides a location property with either 'tick' or 'tooltip'.

In this demo, you can see:

• The country axis displays only the country code
• The label displays annotated data Country: name (code)

Label formatting

The label text inside the tooltip can also be formatted conditionally by providing a function to the series label property.

<LineChart
  // ...
  series={[
    {
      data: [ ... ],
      label: (location) => location === 'tooltip' ? 'BR' : 'Brazil'
    }
  ]}
/>

Hiding values

You can hide the axis value with hideTooltip in the xAxis props. It will remove the header showing the x-axis value from the tooltip.

<LineChart
  // ...
  xAxis={[{ data: [ ... ], hideTooltip: true }]}
/>

Overriding content

To modify the tooltip content, use slots.itemContent or slots.axisContent. The first one is rendered when tooltip trigger is set to "item". The second one when trigger is set to "axis".

// With single component
<LineChart
  slots={{
    itemContent: CustomItemTooltip
  }}
/>

// With composition
<ChartContainer>
  // ...
  <Tooltip
    trigger='item'
    slots={{
      itemContent: CustomItemTooltip
    }}
  />
</ChartContainer>

Composition

If you're using composition, by default, the axis will be listening for mouse events to get its current x/y values. If you don't need it, you can disable those listeners with the disableAxisListener prop.

You need those listeners if you are using axes highlight or you have a tooltip triggered by axis.

<ChartContainer {...} disableAxisListener>
  {/* ... */}
</ChartContainer>

Overriding content

Item Tooltip

You can create your own tooltip by using useItemTooltip. This hook returns the information about the current item user is interacting with. It contains:

• identifier: An object that identify the item. Which often contains its series type, series id, and data index.
• color: The color used to display the item. This includes the impact of color map.
• label, value, formattedValue: Values computed to simplify the tooltip creation.

To follow the mouse position, you can use the useMouseTracker, or track events on the SVG thanks to useSvgRef.

Axis Tooltip

Like in previous section, you can create your own tooltip by using useAxisTooltip. This hook returns the information about the current axis user is interacting with and the relevant series. It contains:

• identifier: An object that identify the axis. Which often contains its series type, series id, and data index.
• color: The color used to display the item. This includes the impact of color map.
• label, value, formattedValue: Values computed to simplify the tooltip creation.

To follow the mouse position, you can use the useMouseTracker, or track events on the SVG thanks to useSvgRef.

Tooltip position

This demo show example about how to use additional hooks such as useXAxis or useDrawingArea to customize the tooltip position.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <ChartsAxisHighlight />
• <ChartsTooltip />
• <DefaultChartsAxisTooltipContent />
• <DefaultChartsItemTooltipContent />