Search

React ChartsTooltips

Tooltips allow users to see extra contextual information without overcrowding the chart.

Default Tooltip

The tooltip content is based on the data values and keys of the series. Additionally, a title or heading will be shown if name properties are provided for the data keys.

series: [
    { type: 'bar', xKey: 'month', stacked: true, yKey: 'value1', yName: 'Sweaters Made' },
    { type: 'bar', xKey: 'month', stacked: true, yKey: 'hats_made', yName: 'Hats Made' },
],

In this example:

  • The tooltip header is visible when yName is provided on the series, and hidden when the yName is omitted.
  • The yName changes are reflected in the legend as well.

The name keys mirror the data keys and differ between series types. See the series specific API Reference for more details.

Tooltip Position

The tooltip position can be changed using the tooltip.position.type property, and further modified using xOffset and yOffset.

Use the buttons to switch between position types top-right, pointer and node.

tooltip: {
    position: {
        type: 'pointer',
        xOffset: 80,
        yOffset: 80,
    },
},

In this configuration:

  • Instead of the tooltip being anchored to the highlighted marker node, it can be anchored to a fixed position or to the mouse pointer.
  • The xOffset and yOffset options define the distance in pixels from the bottom centre of the tooltip to the anchor point.
  • By default, when tooltip.position.xOffset or tooltip.position.yOffset are configured, the tooltip arrow is removed.

Options for tooltip.position.type include:

  • node - Anchors the tooltip to the highlighted node. This is the default for marker-based series such as line and scatter.
  • pointer - Anchors the tooltip to the mouse pointer. This is the default for shape-based series such as bar and pie.
  • Specific canvas positions such as top, right, top-right.

Tooltip Arrow

The default tooltip displays an arrow below it to indicate its exact point of origin. This is removed when the tooltip is constrained by the container or has a position offset supplied.

Use the tooltip.showArrow option to change this behaviour.

tooltip: {
    showArrow: false,
},

Customisation

The exact contents and structure of a tooltip depends on the series and keys used.

Tooltips can contain any number of the following items, in order:-

  • A heading - typically the x-value for a cartesian series.
  • A series symbol - this graphically depicts a series and usually matches the legend item.
  • A title - typically the identifying value for non-cartesian series.
  • Some data rows - these contain one or more label and value pairs corresponding to information for a series.

Using CSS Styles

The default tooltip uses the following CSS classes for the tooltip elements:

  • ag-charts-tooltip for the entire tooltip container.
  • ag-charts-tooltip-heading and ag-charts-tooltip-title for the tooltip headings and titles.
  • ag-charts-tooltip-symbol for the series symbol.
  • ag-charts-tooltip-label and ag-charts-tooltip-value for the elements in the data rows.

Adding custom CSS to these will change the styling of all the tooltips in your app.

.ag-charts-tooltip {
    background-color: papayawhip;
    border: 2px solid peachpuff;
    color: maroon;
}

.ag-charts-tooltip-heading {
    font-weight: bold;
}

Note that your styles don't override the default tooltip styles but complement them.

Modifying Content

The tooltip's content can be customised within the default template by using a renderer callback function.

tooltip: {
    renderer: function ({ datum, xKey, yKey }) {
        return {
            heading: 'Clothing Production',
            title: yName.toUpperCase(),
            data: [
                {
                    label: datum[xKey],
                    value: datum[yKey].toFixed(1),
                },
            ],
        };
    },
},

In this configuration:

  • The renderer receives values associated with the highlighted data point. The actual type of the params object passed into the tooltip renderer will depend on the series type being used.
  • The renderer returns an object with optional heading, title, and data fields.
  • The heading and title must be plain text.
  • The data field consists of an array of label and value fields, which are both plain text.

Using Custom Tooltips

To use a completely custom tooltip instead of modifying the contents of the default tooltip template, return an HTML string to the renderer including all the markup required.

series: [
    {
        type: 'bar',
        tooltip: {
            renderer: function (params) {
                return (
                    '<div class="my-tooltip" style="--color:' +
                    params.fill +
                    '">' +
                    params.datum[params.xKey] +
                    '&nbsp;&#10172;&nbsp;' +
                    params.datum[params.yKey].toFixed(0) +
                    '</div>'
                );
            },
        },
    },
],

In this configuration:

  • The renderer receives values associated with the highlighted data point. The actual type of the params object passed into the tooltip renderer will depend on the series type being used.
  • The renderer returns a single HTML string.
  • The text gets its colour from the fill property in the params object. This matches the colour of the series.
  • The label comes from params.datum[params.xKey] which is the name of the month.
  • The value comes from the params.datum[params.yKey], which we then stringify as an integer via toFixed(0).
  • We used a custom class names on the returned div element, so that we can apply custom styling.

Tooltip Range

The tooltip.range property specifies how near the cursor must be to a node for the tooltip to appear. This can be defined on each series, as well as on the chart level.

Options for tooltip.range are:

  • 'nearest' - Always shows the tooltip of the nearest node. This is the default for marker-based series such as line and scatter.
  • 'exact' - Only shows the tooltip when the user hovers over a node. This is the default for shape-based series such as bar and pie.
  • An integer - Only shows the tooltip when the cursor is within the specified pixel distance of a node.

Interaction with Tooltips

By default, you cannot hover over a tooltip or select its text.

Set the series[].tooltip.interaction.enabled flag to true to enable selecting the text and clicking links within the tooltip.

API Reference