Tooltips

Tooltip Configuration

The tooltip configuration is passed into the options.tooltips namespace. The global options for the chart tooltips is defined in Chart.defaults.global.tooltips.

NameTypeDefaultDescription
enabledbooleantrueAre on-canvas tooltips enabled?
customfunctionnullSee custom tooltip section.
modestring‘nearest’Sets which elements appear in the tooltip. more….
intersectbooleantrueIf true, the tooltip mode applies only when the mouse position intersects with an element. If false, the mode will be applied at all times.
positionstring‘average’The mode for positioning the tooltip. more…
callbacksobjectSee the callbacks section.
itemSortfunctionSort tooltip items. more…
filterfunctionFilter tooltip items. more…
backgroundColorColor‘rgba(0, 0, 0, 0.8)’Background color of the tooltip.
titleFontFamilystring“‘Helvetica Neue’, ‘Helvetica’, ‘Arial’, sans-serif”Title font.
titleFontSizenumber12Title font size.
titleFontStylestring‘bold’Title font style.
titleFontColorColor‘#fff’Title font color.
titleAlignstring‘left’Horizontal alignment of the title text lines. more…
titleSpacingnumber2Spacing to add to top and bottom of each title line.
titleMarginBottomnumber6Margin to add on bottom of title section.
bodyFontFamilystring“‘Helvetica Neue’, ‘Helvetica’, ‘Arial’, sans-serif”Body line font.
bodyFontSizenumber12Body font size.
bodyFontStylestring‘normal’Body font style.
bodyFontColorColor‘#fff’Body font color.
bodyAlignstring‘left’Horizontal alignment of the body text lines. more…
bodySpacingnumber2Spacing to add to top and bottom of each tooltip item.
footerFontFamilystring“‘Helvetica Neue’, ‘Helvetica’, ‘Arial’, sans-serif”Footer font.
footerFontSizenumber12Footer font size.
footerFontStylestring‘bold’Footer font style.
footerFontColorColor‘#fff’Footer font color.
footerAlignstring‘left’Horizontal alignment of the footer text lines. more…
footerSpacingnumber2Spacing to add to top and bottom of each footer line.
footerMarginTopnumber6Margin to add before drawing the footer.
xPaddingnumber6Padding to add on left and right of tooltip.
yPaddingnumber6Padding to add on top and bottom of tooltip.
caretPaddingnumber2Extra distance to move the end of the tooltip arrow away from the tooltip point.
caretSizenumber5Size, in px, of the tooltip arrow.
cornerRadiusnumber6Radius of tooltip corner curves.
multiKeyBackgroundColor‘#fff’Color to draw behind the colored boxes when multiple items are in the tooltip.
displayColorsbooleantrueIf true, color boxes are shown in the tooltip.
borderColorColor‘rgba(0, 0, 0, 0)’Color of the border.
borderWidthnumber0Size of the border.
rtlbooleantrue for rendering the legends from right to left.
textDirectionstringcanvas’ defaultThis will force the text direction 'rtl'</td><td>'ltr on the canvas for rendering the tooltips, regardless of the css specified on the canvas

Position Modes

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.

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

Example:

  1. /**
  2. * Custom positioner
  3. * @function Chart.Tooltip.positioners.custom
  4. * @param elements {Chart.Element[]} the tooltip elements
  5. * @param eventPosition {Point} the position of the event in canvas coordinates
  6. * @returns {Point} the tooltip position
  7. */
  8. Chart.Tooltip.positioners.custom = function(elements, eventPosition) {
  9. /** @type {Chart.Tooltip} */
  10. var tooltip = this;
  11. /* ... */
  12. return {
  13. x: 0,
  14. y: 0
  15. };
  16. };

Alignment

The titleAlign, bodyAlign and footerAlign options define the horizontal position of the text lines with respect to the tooltip box. The following values are supported.

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

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

Sort Callback

Allows sorting of tooltip items. Must implement at minimum a function that can be passed to Array.prototype.sort. 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 Array.prototype.filter. This function can also accept a second parameter that is the data object passed to the chart.

Tooltip Callbacks

The tooltip label configuration is nested below the tooltip configuration using the callbacks key. The tooltip has the following callbacks for providing text. For all functions, this will be the tooltip object created from the Chart.Tooltip constructor.

All functions are called with the same arguments: a tooltip item and the data object passed to the chart. All functions must return either a string or an array of strings. Arrays of strings are treated as multiple lines of text.

NameArgumentsDescription
beforeTitleTooltipItem[], objectReturns the text to render before the title.
titleTooltipItem[], objectReturns text to render as the title of the tooltip.
afterTitleTooltipItem[], objectReturns text to render after the title.
beforeBodyTooltipItem[], objectReturns text to render before the body section.
beforeLabelTooltipItem, objectReturns text to render before an individual label. This will be called for each item in the tooltip.
labelTooltipItem, objectReturns text to render for an individual item in the tooltip. more…
labelColorTooltipItem, ChartReturns the colors to render for the tooltip item. more…
labelTextColorTooltipItem, ChartReturns the colors for the text of the label for the tooltip item.
afterLabelTooltipItem, objectReturns text to render after an individual label.
afterBodyTooltipItem[], objectReturns text to render after the body section.
beforeFooterTooltipItem[], objectReturns text to render before the footer section.
footerTooltipItem[], objectReturns text to render as the footer of the tooltip.
afterFooterTooltipItem[], objectText to render after the footer section.

Label Callback

The label callback can change the text that displays for a given data point. A common example to round data values; the following example rounds the data to two decimal places.

  1. var chart = new Chart(ctx, {
  2. type: 'line',
  3. data: data,
  4. options: {
  5. tooltips: {
  6. callbacks: {
  7. label: function(tooltipItem, data) {
  8. var label = data.datasets[tooltipItem.datasetIndex].label || '';
  9. if (label) {
  10. label += ': ';
  11. }
  12. label += Math.round(tooltipItem.yLabel * 100) / 100;
  13. return label;
  14. }
  15. }
  16. }
  17. }
  18. });

Label Color Callback

For example, to return a red box for each item in the tooltip you could do:

  1. var chart = new Chart(ctx, {
  2. type: 'line',
  3. data: data,
  4. options: {
  5. tooltips: {
  6. callbacks: {
  7. labelColor: function(tooltipItem, chart) {
  8. return {
  9. borderColor: 'rgb(255, 0, 0)',
  10. backgroundColor: 'rgb(255, 0, 0)'
  11. };
  12. },
  13. labelTextColor: function(tooltipItem, chart) {
  14. return '#543453';
  15. }
  16. }
  17. }
  18. }
  19. });

Tooltip Item Interface

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

  1. {
  2. // Label for the tooltip
  3. label: string,
  4. // Value for the tooltip
  5. value: string,
  6. // X Value of the tooltip
  7. // (deprecated) use `value` or `label` instead
  8. xLabel: number | string,
  9. // Y value of the tooltip
  10. // (deprecated) use `value` or `label` instead
  11. yLabel: number | string,
  12. // Index of the dataset the item comes from
  13. datasetIndex: number,
  14. // Index of this data item in the dataset
  15. index: number,
  16. // X position of matching point
  17. x: number,
  18. // Y position of matching point
  19. y: number
  20. }

External (Custom) Tooltips

Custom 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 oncanvas one. You can enable custom tooltips in the global or chart configuration like so:

  1. var myPieChart = new Chart(ctx, {
  2. type: 'pie',
  3. data: data,
  4. options: {
  5. tooltips: {
  6. // Disable the on-canvas tooltip
  7. enabled: false,
  8. custom: function(tooltipModel) {
  9. // Tooltip Element
  10. var tooltipEl = document.getElementById('chartjs-tooltip');
  11. // Create element on first render
  12. if (!tooltipEl) {
  13. tooltipEl = document.createElement('div');
  14. tooltipEl.id = 'chartjs-tooltip';
  15. tooltipEl.innerHTML = '<table></table>';
  16. document.body.appendChild(tooltipEl);
  17. }
  18. // Hide if no tooltip
  19. if (tooltipModel.opacity === 0) {
  20. tooltipEl.style.opacity = 0;
  21. return;
  22. }
  23. // Set caret Position
  24. tooltipEl.classList.remove('above', 'below', 'no-transform');
  25. if (tooltipModel.yAlign) {
  26. tooltipEl.classList.add(tooltipModel.yAlign);
  27. } else {
  28. tooltipEl.classList.add('no-transform');
  29. }
  30. function getBody(bodyItem) {
  31. return bodyItem.lines;
  32. }
  33. // Set Text
  34. if (tooltipModel.body) {
  35. var titleLines = tooltipModel.title || [];
  36. var bodyLines = tooltipModel.body.map(getBody);
  37. var innerHtml = '<thead>';
  38. titleLines.forEach(function(title) {
  39. innerHtml += '<tr><th>' + title + '</th></tr>';
  40. });
  41. innerHtml += '</thead><tbody>';
  42. bodyLines.forEach(function(body, i) {
  43. var colors = tooltipModel.labelColors[i];
  44. var style = 'background:' + colors.backgroundColor;
  45. style += '; border-color:' + colors.borderColor;
  46. style += '; border-width: 2px';
  47. var span = '<span style="' + style + '"></span>';
  48. innerHtml += '<tr><td>' + span + body + '</td></tr>';
  49. });
  50. innerHtml += '</tbody>';
  51. var tableRoot = tooltipEl.querySelector('table');
  52. tableRoot.innerHTML = innerHtml;
  53. }
  54. // `this` will be the overall tooltip
  55. var position = this._chart.canvas.getBoundingClientRect();
  56. // Display, position, and set styles for font
  57. tooltipEl.style.opacity = 1;
  58. tooltipEl.style.position = 'absolute';
  59. tooltipEl.style.left = position.left + window.pageXOffset + tooltipModel.caretX + 'px';
  60. tooltipEl.style.top = position.top + window.pageYOffset + tooltipModel.caretY + 'px';
  61. tooltipEl.style.fontFamily = tooltipModel._bodyFontFamily;
  62. tooltipEl.style.fontSize = tooltipModel.bodyFontSize + 'px';
  63. tooltipEl.style.fontStyle = tooltipModel._bodyFontStyle;
  64. tooltipEl.style.padding = tooltipModel.yPadding + 'px ' + tooltipModel.xPadding + 'px';
  65. tooltipEl.style.pointerEvents = 'none';
  66. }
  67. }
  68. }
  69. });

See samples for examples on how to get started with custom tooltips.

Tooltip Model

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

  1. {
  2. // The items that we are rendering in the tooltip. See Tooltip Item Interface section
  3. dataPoints: TooltipItem[],
  4. // Positioning
  5. xPadding: number,
  6. yPadding: number,
  7. xAlign: string,
  8. yAlign: string,
  9. // X and Y properties are the top left of the tooltip
  10. x: number,
  11. y: number,
  12. width: number,
  13. height: number,
  14. // Where the tooltip points to
  15. caretX: number,
  16. caretY: number,
  17. // Body
  18. // The body lines that need to be rendered
  19. // Each object contains 3 parameters
  20. // before: string[] // lines of text before the line with the color square
  21. // lines: string[], // lines of text to render as the main item with color square
  22. // after: string[], // lines of text to render after the main lines
  23. body: object[],
  24. // lines of text that appear after the title but before the body
  25. beforeBody: string[],
  26. // line of text that appear after the body and before the footer
  27. afterBody: string[],
  28. bodyFontColor: Color,
  29. _bodyFontFamily: string,
  30. _bodyFontStyle: string,
  31. _bodyAlign: string,
  32. bodyFontSize: number,
  33. bodySpacing: number,
  34. // Title
  35. // lines of text that form the title
  36. title: string[],
  37. titleFontColor: Color,
  38. _titleFontFamily: string,
  39. _titleFontStyle: string,
  40. titleFontSize: number,
  41. _titleAlign: string,
  42. titleSpacing: number,
  43. titleMarginBottom: number,
  44. // Footer
  45. // lines of text that form the footer
  46. footer: string[],
  47. footerFontColor: Color,
  48. _footerFontFamily: string,
  49. _footerFontStyle: string,
  50. footerFontSize: number,
  51. _footerAlign: string,
  52. footerSpacing: number,
  53. footerMarginTop: number,
  54. // Appearance
  55. caretSize: number,
  56. caretPadding: number,
  57. cornerRadius: number,
  58. backgroundColor: Color,
  59. // colors to render for each item in body[]. This is the color of the squares in the tooltip
  60. labelColors: Color[],
  61. labelTextColors: Color[],
  62. // 0 opacity is a hidden tooltip
  63. opacity: number,
  64. legendColorBackground: Color,
  65. displayColors: boolean,
  66. borderColor: Color,
  67. borderWidth: number
  68. }