{{ target: partial-tooltip-introduction }}

General Introduction:

tooltip can be configured on different places:

{{ target: partial-tooltip-in-coords }}

tooltip(Object)

{{ if: ${version} }} {{ use: partial-version( version = ‘5.1.0’ ) }} {{ /if }}

tooltip settings in the coordinate system component.

{{ use: partial-tooltip-introduction() }}

{{ use: partial-tooltip-coords-common( prefix = ‘##’, noAxis = ${noAxis} ) }}

{{ use: partial-tooltip-common( scope = ‘coordSys’, prefix = ‘##’ ) }}

{{ target: partial-tooltip-in-coords-item }}

tooltip(Object)

{{ if: ${version} }} {{ use: partial-version( version = ‘5.1.0’ ) }} {{ /if }}

tooltip settings in this ${componentItemDesc}.

{{ use: partial-tooltip-coords-common( prefix = ‘###’, noAxis = ${noAxis} ) }}

{{ use: partial-tooltip-common( scope = ‘coordSysItem’, prefix = ‘###’ ) }}

{{ target: partial-tooltip-in-series }}

tooltip(Object)

tooltip settings in this series.

{{ use: partial-tooltip-common( scope = ‘series’, prefix = ‘##’ ) }}

{{ target: partial-tooltip-in-series-data }}

tooltip(Object)

tooltip settings in this series data.

{{ use: partial-tooltip-common( scope = ‘seriesData’, prefix = ‘###’ ) }}

{{ target: partial-tooltip-scope-tip }}

{{ if: ${scope} === ‘series’ }}

**Notice：**series.tooltip only works when tooltip.trigger is 'item'.

{{ elif: ${scope} === ‘seriesData’ }}

**Notice：**series.data.tooltip only works when tooltip.trigger is 'item'.
{{ /if }}

{{ target: partial-tooltip-coords-common }}

#${prefix} show(boolean) = true

Whether to show the tooltip component.

{{ if: !${noAxis} }} including tooltip floating layer and axisPointer. {{ /if }}

{{ if: !${noAxis} }} #${prefix} trigger(string) = ‘item’

Type of triggering.

Options:

  • 'item'

    Triggered by data item, which is mainly used for charts that don't have a category axis like scatter charts or pie charts.

  • 'axis'

    Triggered by axes, which is mainly used for charts that have category axes, like bar charts or line charts.

    ECharts 2.x only supports axis trigger for category axis. In ECharts 3, it is supported for all types of axes in grid or polar. Also, you may assign axis with axisPointer.axis.

  • 'none'

    Trigger nothing.

#${prefix} axisPointer(Object)

Configuration item for axisPointer.

tooltip.axisPointer is like syntactic sugar of axisPointer settings on axes (for example, xAxis.axisPointer or angleAxis.axisPointer). More detailed features can be configured on someAxis.axisPointer. But in common cases, using tooltip.axisPointer is more convenient.

Notice: configurations of tooltip.axisPointer has lower priority than that of someAxis.axisPointer.

{{ use: partial-axisPointer-introduction() }}

##${prefix} type(string) = ‘line’

Indicator type.

Options:

  • 'line' line indicator.

  • 'shadow' shadow crosshair indicator.

  • 'none' no indicator displayed.

  • 'cross' crosshair indicator, which is actually the shortcut of enable two axisPointers of two orthometric axes.

##${prefix} axis(string) = ‘auto’

The coordinate axis, which could be 'x', 'y', 'radius', or 'angle'. By default, each coordinate system will automatically chose the axes whose will display its axisPointer (category axis or time axis is used by default).

{{ use: partial-axisPointer-tooltip-shared( prefix = “#” + ${prefix} ) }}

##${prefix} crossStyle(Object)

It is valid when axisPointer.type is 'cross'.

{{ use: partial-line-style( prefix = “##” + ${prefix}, defaultColor = “#555”, defaultWidth = 1, defaultType = “dashed” ) }}

{{ use: partial-animation( prefix = ‘#’ + ${prefix}, defaultAnimationEasingUpdate = ‘exponentialOut’, defaultAnimationDurationUpdate = 200 ) }} {{ /if }}

{{ target: partial-tooltip-common }}

#${prefix} position(string|Array)

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

The position of the tooltip's floating layer, which would follow the position of mouse by default.

Options:

  • Array

    Display the position of tooltip's floating layer through array, which supports absolute position and relative percentage.

    Example:

    // absolute position, which is 10px to the left side and 10px to the top side of the container
position: [10, 10]
// relative position, in the exact center of the container
position: ['50%', '50%']

  • Function

    Callback function in the following form:

    (point: Array, params: Object|Array.<Object>, dom: HTMLDomElement, rect: Object, size: Object) => Array

    Parameters:
    point: Mouse position.
    param: The same as formatter.
    dom: The DOM object of tooltip.
    rect: It is valid only when mouse is on graphic elements, which stands for a bounding box with x, y, width, and height.
    size: The size of dom echarts container. For example: {contentSize: [width, height], viewSize: [width, height]}.

    Return:
    Return value is an array standing for tooltip position, which can be absolute pixels, or relative percentage.
    Or can be an object, like {left: 10, top: 30}, or {right: '20%', bottom: 40}.

    For example:

    position: function (point, params, dom, rect, size) {
    // fixed at top
    return [point[0], '10%'];
}

    Or:

    position: function (pos, params, dom, rect, size) {
    // tooltip will be fixed on the right if mouse hovering on the left,
    // and on the left if hovering on the right.
    var obj = {top: 60};
    obj[['left', 'right'][+(pos[0] < size.viewSize[0] / 2)]] = 5;
    return obj;
}

  • 'inside'

    Center position of the graphic element where the mouse is in, which is only valid when trigger is 'item'.

  • 'top'

    Top position of the graphic element where the mouse is in, which is only valid when trigger is 'item'.

  • 'left'

    Left position of the graphic element where the mouse is in, which is only valid when trigger is 'item'.

  • 'right'

    Right position of the graphic element where the mouse is in, which is only valid when trigger is 'item'.

  • 'bottom'

    Bottom position of the graphic element where the mouse is in, which is only valid when trigger is 'item'.

#${prefix} formatter(string|Function)

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

The content formatter of tooltip's floating layer which supports string template and callback function.

1. String template

The template variables are {a}, {b}, {c}, {d} and {e}, which stands for series name, data name and data value and ect. When trigger is set to be 'axis', there may be data from multiple series. In this time, series index can be referred as {a0}, {a1}, or {a2}.

{a}, {b}, {c}, {d} have different meanings for different series types:

  • Line (area) charts, bar (column) charts, K charts: {a} for series name, {b} for category name, {c} for data value, {d} for none;

  • Scatter (bubble) charts: {a} for series name, {b} for data name, {c} for data value, {d} for none;

  • Map: {a} for series name, {b} for area name, {c} for merging data, {d} for none;

  • Pie charts, gauge charts, funnel charts: {a} for series name, {b} for data item name, {c} for data value, {d} for percentage.

**Example: **

formatter: '{b0}: {c0}<br />{b1}: {c1}'

2. Callback function

The format of callback function:

(params: Object|Array, ticket: string, callback: (ticket: string, html: string | HTMLElement | HTMLElement[])) => string | HTMLElement | HTMLElement[]

{{ use: partial-security-warning( desc: ‘tooltip is implemented in HTML (unless tooltip.renderMode is set as richText), allowing users to customize the HTML in this way. The content in the HTML must be properly escaped before being passed in.’ )}}

HTML-escaping must be enforced before passing the HTML to ECharts. For example,

{
    tooltip: {
        formatter: params => {
            const { name, value } = params;
            // HTML-escaping must be performed.
            // Otherwise, the rendering may be incorrect if `name` or
            // `value` contain special charactors like '<', '>', etc.
            // Additionally, unescaped strings may introduces XSS risks
            // if `name` or `value` come from untrusted sources, where
            // malicious code may be injected into that strings.
            return echarts.format.encodeHTML(name)
                + '<b>' + echarts.format.encodeHTML(value) + '</b>';
            // NOTE: `echarts.format.encodeHTML` is an utility that converts special
            //  characters ('&', '<', '>', '"', "'") to their corresponding HTML entities.
            //  This is just an example -- any HTML-escaping utility can be used.
        }
    }
}

The first parameter params is the data that the formatter needs. Its format is shown as follows:

{{ use: partial-formatter-params-structure( extra = { percent: { desc: ‘The percentage of current data item in the pie/funnel series’, type: ‘number’ }, treePathInfo: { desc: ‘The ancestors of current node in the sunburst series (including self)’, type: ‘Array’ }, treeAncestors: { desc: ‘The ancestors of current node in the tree/treemap series (including self)’, type: ‘Array’ }, isTruncated: { desc: ‘A function that returns a boolean value to flag if the axis label is truncated’, type: ‘Function’ }, tickIndex: { desc: ‘Current index of the axis label tick’, type: ‘number’ } } ) }}

When trigger is 'axis', or when tooltip is triggered by axisPointer, params is the data array of multiple series. The content of each item of the array is the same as above. Besides,

{{ use: partial-formatter-params-structure() }}

**Note: **Using array to present all the parameters in ECharts 2.x is not supported anymore.

The second parameter ticket is the asynchronous callback flag which should be used along with the third parameter callback when it is used.

The third parameter callback is asynchronous callback. When the content of tooltip is acquired asynchronously, ticket and htm as introduced above can be used to update tooltip with callback.

Example:

formatter: function (params, ticket, callback) {
    $.get('detail?name=' + params.name, function (content) {
        callback(ticket, toHTML(content));
    });
    return 'Loading';
}

{{ if: !${noValueFormatter} }} #${prefix} valueFormatter(string)

{{ use: partial-version( version = ‘5.3.0’ ) }}

Callback function for formatting the value section in tooltip.

Interface:

(value: number | string, dataIndex: number) => string

{{ use: partial-version( feature = ‘dataIndex is provided; but not reasonable when dataZoom exists, since it is the index after dataZoom filtering.’, version = ‘5.5.0’ ) }} {{ use: partial-version( feature = ‘dataIndex is corrected to the index before dataZoom filtering.’, version = ‘6.1.0’ ) }}

Example:

// Add $ prefix
valueFormatter: (value) => '$' + value.toFixed(2)

[NOTE]: Different from tooltip.formater, raw HTML is NOT accepted in this approach -- the returned content will be escaped internally before rendering. {{ /if }}

#${prefix} backgroundColor(Color) = ‘rgba(50,50,50,0.7)’

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

The background color of tooltip's floating layer.

#${prefix} borderColor(Color) = ‘#333’

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

The border color of tooltip's floating layer.

#${prefix} borderWidth(number) = 0

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

The border width of tooltip's floating layer.

#${prefix} padding(number) = 5

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

{{ use: partial-padding( componentName = ‘The floating layer of tooltip’ ) }}

#${prefix} textStyle(Object)

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

The text style of tooltip's floating layer.

{{ use: partial-simple-text-style( prefix = “#” + ${prefix}, defaultColor = “‘#fff’”, defaultFontSize = 14 ) }}

#${prefix} extraCssText(string)

{{ use: partial-tooltip-scope-tip( scope = ${scope} ) }}

Extra CSS style for floating layer. The following is an example for adding shadow.

extraCssText: 'box-shadow: 0 0 3px rgba(0, 0, 0, 0.3);'

{{ use: partial-security-warning( desc: ‘tooltip is implemented in HTML (unless tooltip.renderMode is set as richText), allowing users to customize the CSS text of the box in this way.’, securityRiskExclamation: ‘Security risks must be considered if the CSS text comes from untrusted sources.’ )}}