JavaScript ChartsTooltips

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

Default Tooltip Copy

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 Modes Copy

By default, the tooltip will show the data for a single node. Use the mode option to show a shared or compact tooltip.

// Chart options only
tooltip: {
    mode: 'shared', // or 'single' or 'compact'
}

The options for mode are:

• single - shows a title, symbol and data values for a single series.
• shared - shows a merged tooltip, combining the tooltips of all series sharing the same x-value.
• compact - shows fewer data fields and uses less padding.

Tooltip Position Copy

The tooltip is anchored to the node. Use tooltip.position.anchorTo, and optionally tooltip.position.placement, to change this.

tooltip: {
    position: {
        anchorTo: 'node',
        placement: 'top',
    },
},

Fallback positions can be provided in an array of placement values. The tooltip will use the first position that has sufficient space.

tooltip: {
    position: {
        anchorTo: 'node',
        placement: ['left', 'right'],
    },
},

In the above example:

• Change the 'Placement' dropdown to 'Left + Right fallback'.
• Hover the leftmost datapoint and see that the tooltip goes to the right of the marker as there is no room on the left.

The options for anchorTo are:

• node - the datapoint, such as the marker or bar.
• pointer - the mouse pointer or single finger touch position.
• chart - the chart container.

The tooltip position can be further customised by setting the tooltip.position.xOffset and tooltip.position.yOffset properties, which will move the tooltip by the specified number of pixels in the x and y directions, respectively.

Tooltip Arrow Copy

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,
},

Tooltip Pagination Copy

Pagination allows cycling through overlapping datapoints by hovering and then clicking on the mouse. Use pagination: true to enable.

Pagination will only become available when two or more data points are under the cursor.

// Chart options only
tooltip: {
    pagination: true,
}

In the above example:

• Hover overlapping bubbles.
• The cursor turns into a hand and the tooltip displays the number of data points under the cursor.
• Click in the current position to cycle through the data points, highlighting and displaying the tooltip for each in turn.

Customisation Copy

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 Copy

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 Copy

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 Copy

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 Copy

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 Copy

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 Copy