AG Studio Launch Week 🚀🚀🚀 28 Sep - 2 Oct 2026 🚀🚀🚀 Join now
AG Grid
Best JavaScript Grid in the World
AG Charts
Best JavaScript Charts in the World
AG Studio
Best JavaScript Dashboard in the World
Bryntum Gantt
Speed-tuned Gantt chart for project planning
Bryntum Scheduler
Resource scheduling timeline component
PROPRO
Bryntum Scheduler Pro
Scheduler with auto-scheduling and constraints
Bryntum Calendar
Flexible JavaScript event calendar
Bryntum Task Board
Kanban-style task board component
Search⌘ KCtrl K
What's New
Getting started
Quick StartKey FeaturesCommunity vs. Enterprise
AI Features
Skills
Core features
Specialised Charts
Org ChartQuadrant Chart
Series
BarLineAreaScatterBubblePieDonutCombinationBox PlotCandlestickOHLCHeatmapHistogramNightingaleRadar AreaRadar LineRadial BarRadial ColumnRange AreaRange BarWaterfallSunburstTreemapSankeyChordFunnelCone FunnelPyramid
Gauges
Radial GaugeLinear Gauge

JavaScript ChartsTooltips

Version 14.2.0

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

This page covers Series tooltips. For tooltips on other chart elements, see the API options for title, subtitle, footnote, and legend items.

Default Tooltip Copy Link

The tooltip content is based on the data values and keys of the series. If provided, the _Name properties will be used instead of the _Key properties.

 
{
    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 yName is used in the tooltip and legend when provided.
  • The default tooltip mode is:
    • compact when showing a single series with no yName.
    • single when showing more than 3 series, or a single series with yName.
    • shared when showing 3 or fewer series.

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

Tooltip Modes Copy Link

By default a shared tooltip will be used for most cartesian charts containing 3 or fewer series. Use the mode option to show a single, shared or compact tooltip.

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

See Highlight Modes to apply the same shared grouping to series highlighting.

Tooltip Position Copy Link

By default the tooltip is anchored to the hovered datapoint. Use placement, anchorTo and offset to customise this.

 
{
    tooltip: {
        position: {
            anchorTo: 'node',
            placement: ['top', 'bottom', 'left', 'right'],
            offset: 12,
        },
    },
}

Placement Copy Link

The placement option positions the tooltip relative to its anchor point, such as top or top-right. See the API Reference for the full list of values.

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.

Anchor Point Copy Link

The options for anchorTo are:

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

Offset Copy Link

Use tooltip.position.offset to control the gap between the tooltip and its anchor point in the placement direction, or xOffset and yOffset for specific horizontal and vertical offsets.

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

In the above example:

  • Change the 'Placement' dropdown to 'Left + Right fallback' and change the 'Offset' value.
  • Hover the leftmost datapoint and see that the offset is applied to the right of the marker, hover the rightmost datapoint and see that the offset is applied to the left.
  • The directional offset can be used together with xOffset and yOffset.

Tooltip Arrow Copy Link

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 an xOffset or yOffset supplied. The directional offset does not suppress the arrow.

Use the tooltip.showArrow option to change this behaviour.

{
    tooltip: {
        showArrow: false,
    },
}

Tooltip Pagination Copy Link

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.

{
    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 Link

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 Link

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 Link

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

 
{
    tooltip: {
        renderer: function ({ datum, xKey, yKey, yName }) {
            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, symbol, 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.
  • Returning an empty string for any field will cause it to be omitted from the rendered tooltip.

Modifying the Symbol Copy Link

The tooltip symbol (the coloured marker that represents the series) can be customised using the symbol property in the renderer's return object.

Whether the symbol defaults to use a marker, line, or both depends on the series type and options used. Use the enabled option for each element to override this.

 
{
    tooltip: {
        renderer: function () {
            return {
                symbol: {
                    marker: {
                        enabled: true,
                        shape: 'star',
                        fill: '#cc0000',
                    },
                    line: {
                        enabled: true,
                        stroke: '#ff6b00',
                    },
                },
            };
        },
    },
}

In this example:

  • Click the button to toggle the symbol. This will take effect on the next hover.
  • The marker shape has been changed to 'star' instead of inheriting the circle shape from the series.
  • The marker and line colours have been changed from those used in the series.

Using Custom Tooltips Copy Link

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 Link

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 Link

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 Link

Properties available on the AgChartTooltipOptions interface.

enabled boolean
Set to `false` to disable tooltips for all series in the chart.
mode AgTooltipMode
Group multiple series into the same tooltip
showArrow boolean
The tooltip arrow is displayed by default, unless the container restricts it or a position offset is provided. To always display the arrow, set `showArrow` to `true`. To remove the arrow, set `showArrow` to `false`.
range InteractionRange
Range from a point that triggers the tooltip to show. This will be used unless overridden by the series `tooltip.range` option.
position AgTooltipPositionOptions
The position of the tooltip. This will be used unless overridden by the series `tooltip.range` option.
pagination boolean
The configuration for tooltip pagination.
delay DurationMs
The time interval (in milliseconds) after which the tooltip is shown.
wrapping TextWrap default: 'hyphenate'
Text wrapping strategy for tooltips. - `'always'` will always wrap text to fit within the tooltip. - `'hyphenate'` is similar to `'always'`, but inserts a hyphen (`-`) if forced to wrap in the middle of a word. - `'on-space'` will only wrap on white space. If there is no possibility to wrap a line on space and satisfy the tooltip dimensions, the text will be truncated. - `'never'` disables text wrapping.

Properties available on the AgSeriesTooltip interface.

enabled boolean
Whether to show tooltips when the series are hovered over.
showArrow boolean
The tooltip arrow is displayed by default, unless the container restricts it or a position offset is provided. To always display the arrow, set `showArrow` to `true`. To remove the arrow, set `showArrow` to `false`.
range InteractionRange
Range from a point that triggers the tooltip to show. Each series type uses its own default; typically this is `'nearest'` for marker-based series and `'exact'` for shape-based series.
position AgTooltipPositionOptions
The position of the tooltip. Each series type uses its own default; typically this is `'node'` for marker-based series and `'pointer'` for shape-based series.
interaction AgSeriesTooltipInteraction
Configuration for tooltip interaction.
renderer Renderer
Function used to create the content for tooltips.