tooltip component overview
The tooltip component displays information when users interact with the chart. It is configured via the tooltip object in the chart option.
tooltip
40 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
showContent default value
showContent is a boolean option with default value true. When true, the tooltip floating layer is shown. Set to false to trigger tooltip events or show the axisPointer without displaying tooltip content.
alwaysShowContent default value and behavior
alwaysShowContent is a boolean option with default value false. When false, tooltip content is hidden after a delay controlled by hideDelay. When true, tooltip content is displayed persistently.
triggerOn options and default
triggerOn is a string option with default value 'mousemove|click'. Valid options are: 'mousemove' (trigger on mouse move), 'click' (trigger on mouse click), 'mousemove|click' (trigger on both mouse move and click), and 'none' (no automatic trigger, use action.tooltip.showTip and action.tooltip.hideTip instead, or axisPointer.handle).
showDelay default value
showDelay is a number option with default value 0, representing delay time for showing tooltip in milliseconds. No delay is applied by default, and setting a delay is not recommended. Only valid when triggerOn is set to 'mousemove'.
hideDelay default value
hideDelay is a number option with default value 100, representing delay time for hiding tooltip in milliseconds. This option is invalid when alwaysShowContent is true.
enterable default value
enterable is a boolean option with default value false. When true, allows the mouse to enter the tooltip floating layer, enabling interactions with links, buttons, and other elements inside the tooltip.
renderMode options and default
renderMode is a string option with default value 'html'. Options are: 'html' (renders tooltip as extra DOM element) and 'richText' (renders tooltip inside Canvas). richText mode is useful for environments without DOM, such as WeChat applications.
confine default value
confine is a boolean option with default value false. When true, confines tooltip content within the chart instance's view rect, preventing tooltip from being cut off due to 'overflow: hidden' on outer DOM or narrow mobile screens.
appendToBody deprecated in v5.5.0
appendToBody is a boolean option with default value false, deprecated since version 5.5.0 in favor of appendTo. When true and renderMode is 'html', appends tooltip DOM element as a child of the HTML body element to prevent tooltip cutoff when overflow: hidden is set on ancestor elements.
appendTo option for tooltip DOM placement
appendTo specifies which DOM element to append the tooltip to. Available since version 5.5.0 and only works when renderMode is 'html'. Value can be a string selector, HTMLElement reference, or a function with signature (chartContainer: HTMLElement) => HTMLElement | undefined | null. Returning undefined or null uses default logic. Returns an HTMLElement to specify where tooltip should be appended. Works with CSS transform.
className option for tooltip styling
className is a string option available since version 5.0.0 that specifies CSS classes for the tooltip root DOM element. Only works in 'html' render mode. Example: 'echarts-tooltip echarts-tooltip-dark'.
transitionDuration default value
transitionDuration is a number option with default value 0.4, representing the transition duration of tooltip animation in seconds. When set to 0, tooltip moves closely with the mouse.
displayTransition default value
displayTransition is a boolean option with default value true, available since version 6.0.0. When true, tooltip uses opacity fading for visibility transitions. When false, disables the display transition and sets the DOM element's display property to 'none', which prevents scrollbar visibility issues when tooltip content is large.
order default value and options
order is a string option with default value 'seriesAsc', available since version 5.0.0. Controls tooltip ordering for multiple series. Options are: 'seriesAsc' (series declaration ascending order), 'seriesDesc' (series declaration descending order), 'valueAsc' (value ascending order, numeric values only), and 'valueDesc' (value descending order, numeric values only).
Tooltip example with time axis and manual triggering
Example showing tooltip configured with triggerOn: 'none' and alwaysShowContent: true for manual control via axisPointer.handle on a time axis. The tooltip position function returns [pt[0], 130] to fix vertical position. Uses legend, xAxis with type 'time', yAxis, grid layout, and two stacked line series with area styling.
Tooltip configuration levels: global, coordinate system, series, series data
Tooltip can be configured at four different levels: globally via tooltip option, in a coordinate system via grid.tooltip, polar.tooltip, or single.tooltip, in a series via series.tooltip, and in each item of series.data via series.data.tooltip.
series.tooltip and series.data.tooltip only work when tooltip.trigger is 'item'
The series.tooltip option only works when tooltip.trigger is set to 'item'. Similarly, series.data.tooltip only works when tooltip.trigger is set to 'item'.
tooltip.show option controls tooltip visibility
The show option (boolean, default: true) controls whether to show the tooltip component, including the tooltip floating layer and axisPointer.
tooltip.trigger option types and behavior
The trigger option (string, default: 'item') controls the type of tooltip triggering. Options are: 'item' (triggered by data item, used for charts without category axes like scatter or pie charts), 'axis' (triggered by axes, used for charts with category axes like bar or line charts, supported for all axis types in grid or polar), and 'none' (trigger nothing).
tooltip.axisPointer configuration
The axisPointer option is a configuration object for axisPointer settings in tooltips. It acts as syntactic sugar for axisPointer settings on individual axes (like xAxis.axisPointer or angleAxis.axisPointer). Configuration on tooltip.axisPointer has lower priority than configuration on specific axes.
tooltip.axisPointer.type options
The type option (string, default: 'line') specifies the axisPointer indicator type. Options are: 'line' (line indicator), 'shadow' (shadow crosshair indicator), 'none' (no indicator displayed), and 'cross' (crosshair indicator, which enables two axisPointers for two orthometric axes).
tooltip.axisPointer.axis option
The axis option (string, default: 'auto') specifies the coordinate axis for the axisPointer. Possible values are 'x', 'y', 'radius', or 'angle'. By default, each coordinate system automatically chooses the axes that will display axisPointer, preferring category axes or time axes.
tooltip.axisPointer.crossStyle for cross indicator styling
The crossStyle option is a configuration object valid when axisPointer.type is 'cross'. It supports line style properties like color, width, and type for styling the crosshair indicator.
tooltip.position option array format
The position option (string|Array) controls the tooltip floating layer position. When passed as an array, it supports absolute position in pixels (e.g., [10, 10] for 10px from left and top) or relative percentage (e.g., ['50%', '50%'] for center of container).
tooltip.position function callback parameters
When position is a function, it receives parameters: point (mouse position array), params (same as formatter parameter), dom (tooltip DOM element), rect (bounding box with x, y, width, height when mouse is on graphic elements), and size (container size with {contentSize: [width, height], viewSize: [width, height]}). The function returns an array for tooltip position or an object with left/right and top/bottom properties.
tooltip.position named position options
The position option accepts named string values: 'inside' (center of graphic element, only for trigger:'item'), 'top' (top of graphic element, only for trigger:'item'), 'left' (left of graphic element, only for trigger:'item'), 'right' (right of graphic element, only for trigger:'item'), and 'bottom' (bottom of graphic element, only for trigger:'item').
tooltip.formatter string template variables
The formatter option supports string templates using variables: {a} for series name, {b} for data/category name, {c} for data value, {d} for none or percentage, and {e} for other data. When trigger is 'axis', multiple series data can use {a0}, {a1}, {a2} for different series indices.
tooltip.formatter template variables by series type
Template variable meanings vary by series type: Line/area/bar/column/K charts use {a} for series name, {b} for category name, {c} for data value, {d} for none. Scatter/bubble charts use {a} for series name, {b} for data name, {c} for data value, {d} for none. Map uses {a} for series name, {b} for area name, {c} for merged data, {d} for none. Pie/gauge/funnel charts use {a} for series name, {b} for item name, {c} for data value, {d} for percentage.
tooltip.formatter callback function signature
When formatter is a callback function, its signature is (params: Object|Array, ticket: string, callback: (ticket: string, html: string | HTMLElement | HTMLElement[])) => string | HTMLElement | HTMLElement[]. The params parameter contains formatter data for one or multiple series, ticket is an asynchronous callback flag, and callback is for asynchronous updates.
tooltip.formatter HTML security requirement
Tooltip is implemented in HTML by default (unless renderMode is set to 'richText'). HTML content passed to formatter must be properly escaped to prevent XSS risks. The echarts.format.encodeHTML utility can escape special characters ('&', '<', '>', '"', "'") to their HTML entities.
tooltip.formatter callback example with async content
Example of tooltip formatter with asynchronous callback: formatter: function (params, ticket, callback) { $.get('detail?name=' + params.name, function (content) { callback(ticket, toHTML(content)); }); return 'Loading'; }
tooltip.formatter params structure extra fields for sunburst and tree series
Additional fields in formatter params structure include: percent (percentage of current data item in pie/funnel series, type: number), treePathInfo (ancestors of current node in sunburst series including self, type: Array), treeAncestors (ancestors of current node in tree/treemap series including self, type: Array), isTruncated (function returning boolean if axis label is truncated, type: Function), and tickIndex (current index of axis label tick, type: number).
tooltip.valueFormatter callback for formatting tooltip values
The valueFormatter option (added in version 5.3.0) is a callback function with signature (value: number | string, dataIndex: number) => string that formats the value section in tooltips. Unlike formatter, raw HTML is not accepted and returned content is escaped before rendering. Example: valueFormatter: (value) => '$' + value.toFixed(2). The dataIndex parameter was added in 5.5.0 but corrected in 6.1.0 to represent the index before dataZoom filtering.
tooltip.backgroundColor default and styling
The backgroundColor option (Color, default: 'rgba(50,50,50,0.7)') sets the background color of the tooltip floating layer.
tooltip.borderColor and tooltip.borderWidth options
The borderColor option (Color, default: '#333') sets the border color of the tooltip floating layer. The borderWidth option (number, default: 0) sets the border width of the tooltip floating layer.
tooltip.padding option for floating layer spacing
The padding option (number, default: 5) sets the padding of the tooltip floating layer, supporting individual padding values for top, right, bottom, and left sides (e.g., 5,5,5,5).
tooltip.textStyle for tooltip text styling
The textStyle option is an object that configures the text style of the tooltip floating layer, including properties for color (default: '#fff') and fontSize (default: 14).
tooltip.extraCssText for custom CSS styling
The extraCssText option (string) allows adding extra CSS styles to the tooltip floating layer. Example: extraCssText: 'box-shadow: 0 0 3px rgba(0, 0, 0, 0.3);' for adding shadow. Security risks must be considered if CSS text comes from untrusted sources.
series.tooltip trigger option override
The trigger option in series.tooltip (string|boolean, default: 'item') overrides the global tooltip trigger type for that specific series. Options are 'item', 'axis', or 'none'/false to disable tooltip for that series.