Javascript ChartsTooltips

ReactAngularVueJavascript

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

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.

For specific canvas positions, use tooltip.position.type:

• top
• right
• bottom
• left
• top-left
• top-right
• bottom-right
• bottom-left

The example below demonstrates setting tooltip.position.type and applying an x and y offset.

Use the buttons to switch between positon types top-right, pointer and node (default).

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

In this configuration:

• Instead of the tooltip being anchored to the highlighted marker node, it is anchored 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.

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

Using CSS Styles

The default tooltip uses ag-chart-tooltip, ag-chart-tooltip-title and ag-chart-tooltip-content CSS classes.

<div class="ag-chart-tooltip">
    <div class="ag-chart-tooltip-title"></div>
    <div class="ag-chart-tooltip-content"></div>
</div>

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

Users wishing to modify the tooltip style on a more granular basis, should provide their own tooltip class name via the tooltip.class option. This class name will be added to tooltip element for that particular chart instance.

For example, if we wanted to set the tooltip's content background-color to gold, we'd add a custom class name to our chart in the code:

tooltip: {
    class: 'my-tooltip',
},

And then in the CSS:

.my-tooltip .ag-chart-tooltip-content {
    background-color: gold;
}

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

Modifying Content and Title

To modify the text used for the title and content of a tooltip, use a renderer function.

This receives values associated with the highlighted data point, and should return an object with title and content fields.

tooltip: {
    renderer: function ({ datum, xKey, yKey }) {
        return {
            content: datum[yKey].toFixed(0),
            title: datum[xKey]
        };
    },
},

The title and content fields returned can contain plain text or HTML.

The actual type of the params object passed into the tooltip renderer will depend on the series type being used.

Using Custom Tooltips

Instead of having the tooltip renderer return an object with title and content to be used in the default tooltip template, you can return an HTML string with completely custom markup that will override the entire tooltip template.

series: [
    {
        type: 'bar',
        tooltip: {
            renderer: function ({ datum, xKey, yKey }) {
                return `
            <div class="ag-chart-tooltip-title" style="background-color: ${params.color}">
                ${datum[xKey]}
            </div>
            <div class="ag-chart-tooltip-content">
                ${datum[yKey]}
            </div>`;
            },
        },
    },
],

Notice that in the above example:

• The renderer returns two div elements, one for the tooltip's title and another for its content.
• The value of the title comes from params.datum[params.xKey] which is the name of the month.
• The title element gets its background colour from the params object. The provided colour matches the colour of the series.
• The 'Sweaters Made' value comes from the params.datum[params.yKey], which we then stringify as an integer via toFixed(0).
• We used the default class names on the returned div elements, so that our tooltip gets the default styling. You could however add your own classes to the class list, or replace the default CSS classes with your own. The structure of the returned DOM is also up to you, we are just following the convention for this example.

Tooltip Range

By default, the tooltip for the nearest node is visible when the cursor is on the chart. However, this behaviour can be changed with the chart.tooltip.range property.

The example shows the three types of interaction range:

• 'nearest' (default) will show the tooltip of the nearest node anywhere on the chart.
• 'exact' will show the tooltip when the user hovers over a node.
• An integer will show 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