Tooltip

WARNING

The bubble, doughnut, pie, polar area, and scatter charts override the tooltip defaults. To change the overrides for those chart types, the options are defined in Chart.overrides[type].plugins.tooltip.

Possible modes are:

• 'average'
• 'nearest'

'average' mode will place the tooltip at the average position of the items displayed in the tooltip. 'nearest' will place the tooltip at the position of the element closest to the event position.

You can also define custom position modes.

Tooltip Alignment

The xAlign and yAlign options define the position of the tooltip caret. If these parameters are unset, the optimal caret position is determined.

The following values for the xAlign setting are supported.

• 'left'
• 'center'
• 'right'

The following values for the yAlign setting are supported.

• 'top'
• 'center'
• 'bottom'

Text Alignment

• 'left' (default)
• 'right'
• 'center'

These options are only applied to text lines. Color boxes are always aligned to the left edge.

Allows sorting of . Must implement at minimum a function that can be passed to Array.prototype.sort (opens new window). This function can also accept a third parameter that is the data object passed to the chart.

Filter Callback

Allows filtering of tooltip items. Must implement at minimum a function that can be passed to . This function can also accept a fourth parameter that is the data object passed to the chart.

Namespace: options.plugins.tooltip.callbacks, the tooltip has the following callbacks for providing text. For all functions, this will be the tooltip object created from the Tooltip constructor.

Namespace: data.datasets[].tooltip.callbacks, items marked with Yes in the column Dataset override can be overridden per dataset.

A tooltip item context is generated for each item that appears in the tooltip. This is the primary model that the callback methods interact with. For functions that return text, arrays of strings are treated as multiple lines of text.

Label Callback

The label callback can change the text that displays for a given data point. A common example to show a unit. The example below puts a '$' before every row.

For example, to return a red box with a blue dashed border that has a border radius for each item in the tooltip you could do:

const chart = new Chart(ctx, {
    type: 'line',
    data: data,
    options: {
        plugins: {
            tooltip: {
                callbacks: {
                    labelColor: function(context) {
                        return {
                            borderColor: 'rgb(0, 0, 255)',
                            backgroundColor: 'rgb(255, 0, 0)',
                            borderDash: [2, 2],
                            borderRadius: 2,
                        };
                    },
                    labelTextColor: function(context) {
                        return '#543453';
                }
            }
        }
    }
});

Label Point Style Callback

Tooltip Item Context

The tooltip items passed to the tooltip callbacks implement the following interface.

{
    // The chart the tooltip is being shown on
    chart: Chart
    // Label for the tooltip
    label: string,
    // Parsed data values for the given `dataIndex` and `datasetIndex`
    parsed: object,
    // Raw data values for the given `dataIndex` and `datasetIndex`
    raw: object,
    // Formatted value for the tooltip
    formattedValue: string,
    // The dataset the item comes from
    dataset: object
    // Index of the dataset the item comes from
    datasetIndex: number,
    // Index of this data item in the dataset
    dataIndex: number,
    // The chart element (point, arc, bar, etc.) for this tooltip item
    element: Element,
}

External tooltips allow you to hook into the tooltip rendering process so that you can render the tooltip in your own custom way. Generally this is used to create an HTML tooltip instead of an on-canvas tooltip. The external option takes a function which is passed a context parameter containing the chart and tooltip. You can enable external tooltips in the global or chart configuration like so:

See for examples on how to get started with external tooltips.

The tooltip model contains parameters that can be used to render the tooltip.

{
    chart: Chart,
    // The items that we are rendering in the tooltip. See Tooltip Item Interface section
    dataPoints: TooltipItem[],
    // Positioning
    xAlign: string,
    yAlign: string,
    x: number,
    y: number,
    width: number,
    height: number,
    // Where the tooltip points to
    caretX: number,
    caretY: number,
    // Body
    // The body lines that need to be rendered
    // Each object contains 3 parameters
    // before: string[] // lines of text before the line with the color square
    // lines: string[], // lines of text to render as the main item with color square
    // after: string[], // lines of text to render after the main lines
    body: object[],
    // lines of text that appear after the title but before the body
    beforeBody: string[],
    // line of text that appear after the body and before the footer
    afterBody: string[],
    // Title
    // lines of text that form the title
    title: string[],
    // Footer
    // lines of text that form the footer
    footer: string[],
    // colors to render for each item in body[]. This is the color of the squares in the tooltip
    labelColors: Color[],
    labelTextColors: Color[],
    // 0 opacity is a hidden tooltip
    opacity: number,
    // tooltip options
    options: Object
}

New modes can be defined by adding functions to the Chart.Tooltip.positioners map.

Example:

See samples for a more detailed example.

If you’re using TypeScript, you’ll also need to register the new mode:

declare module 'chart.js' {
  interface TooltipPositionerMap {
    myCustomPositioner: TooltipPositionerFunction<ChartType>;
}