# Tooltip
### How to Register Tooltip Plugin
F2 has modular structure provides best tree-shaking results and package size optimization.
If you just **`import F2 from '@antv/f2'`**, then **it has included tooltip by default**. But if you want a better package size optimization, you can register manually:
```javascript
const F2 = require('@antv/f2/lib/core');
const Tooltip = require('@antv/f2/lib/plugin/tooltip');
// Method 1: Global Registeration
F2.Chart.plugins.register(Tooltip);
// Or Method2: Registeration for a Chart instance
const chart = new Chart({
id: 'canvas',
plugins: Tooltip
});
```
## Tooltip Configuration
### Close Tooltip
If you call `chart.tooltip(false)`, tooltip will not be rendered.
### Configure Tooltip
Below is the method for configuring tooltip, the detail properties can be found in table.
```javascript
chart.tooltip({
// see detail properties in table
});
```
| **Name** | **Type** | **Default** | **Description** |
| -------------------- | -------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `alwaysShow` | Boolean | false | Whether the tooltip is still show when the touch area is not in the chart.It can be set to be `true` to preserve displaying. |
| `offsetX` | Number | 0 | Tooltip offset in x direction. |
| `offsetY` | Number | 0 | Tooltip offset in y direction. |
| `triggerOn` | String / Array | \[ 'touchstart', 'touchmove' ] | The event that will trigger tooltip. |
| `triggerOff` | String / Array | 'touchend' | The event that will hide tooltip. |
| `showTitle` | Boolean | false | Wether to show the title. |
| `showCrosshairs` | Boolean | | Wether to show the tooltip crosshairs. The default value of different charts is different, point, line, area and path will show by default. |
| `crosshairsStyle` | Object | | Style of the crosshairs line, default setting is:
{
stroke: 'rgba(0, 0, 0, 0.25)',
lineWidth: 2
}
|
| `showTooltipMarker` | Boolean | true | Wether to display tooltipMarker. |
| `tooltipMarkerStyle` | Object | | Style of the tooltipMarker. |
| `background` | Object | | The background style of tooltip content box. |
| `titleStyle` | Object | | Style for tooltip's title, invalid if showTitle is `false.` |
| `nameStyle` | Object | | Style for each tooltip item's name part. |
| `valueStyle` | Object | | Style for each tooltip item's value part. |
| `showItemMarker` | Boolean | true | Wether to show the each tooltip item's marker. |
| `itemMarkerStyle` | Object | | Style for each tooltip item's marker. |
| `custom` | Boolean | false | Wether to custom the tooltip. See [custom tooltip](https://antv.gitbook.io/f2/api/tooltip#custom-tooltip). |
| `onShow` | Function | | Callback when the tooltip show. See [callback](https://antv.gitbook.io/f2/api/tooltip#onshow-callback). |
| `onHide` | Function | | Callback when the tooltip hide. See [callback](https://antv.gitbook.io/f2/api/tooltip#onhide-callback). |
| `onChange` | Function | | Callback when the tooltip content change. See [callback](https://antv.gitbook.io/f2/api/tooltip#onchange-callback). |
#### Tooltip Item Interface
The picture below shows the structure of tooltip content, it includes title and a group of items, each item consists of marker, name and value.
The tooltip items passed to the tooltip `onShow` , `onChange`, `onHide` callbacks implement the following interface:
```javascript
{
// X position of matching tooltip item
x: Number,
// Y position of matching tooltip item
y: Number,
// Color of matching tooltip item
color: String,
// The data of matching tooltip item
origin: Object,
// The value of the `name` attribute in tooltip item
name: String,
// The value of the `value` attribute in tooltip item
value: String / Number,
// The title of current tooltip
title: String
// The marker of matching tooltip item
marker: Object
}
```
#### `onShow` callback
We can use `onShow` callback to change the tooltip's show content. It will trigger when the tooltip is shown.
```javascript
chart.tooltip({
onShow(obj) {}
});
// The following is the parameter `Obj` interface
{
// X position of current event
x: Number,
// Y position of current event
y: Number,
// The tootlip instance
tooltip: Object
// Tooltip content items
items: Array,
// The style of tooltipMarker
tooltipMarkerCfg: Object
}
```
As following example, we will change the value of name to the value of title, see demo and code [here](https://antv.alipay.com/zh-cn/f2/3.x/demo/line/basic.html).
```javascript
chart.tooltip({
onShow: function onShow(ev) {
var items = ev.items;
items[0].name = items[0].title;
}
});
```
#### `onChange` callback
It will trigger when the tooltip's content changed. Usually combined with the `custom` attribute for custom tooltip.
```javascript
chart.tooltip({
onChange(obj) {}
});
// The following is the parameter `Obj` interface
{
// X position of current event
x: Number,
// Y position of current event
y: Number,
// The tootlip instance
tooltip: Object
// Tooltip content items
items: Array,
// The style of tooltipMarker
tooltipMarkerCfg: Object
}
```
#### `onHide` callback
It will trigger when the tooltip is disappeared.
```javascript
chart.tooltip({
onHide(obj) {}
});
// The following is the parameter `Obj` interface
{
// The tootlip instance
tooltip: Object
}
```
### Custom Tooltip
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](https://antv.gitbook.io/f2/api/tooltip#external-html-tooltip) instead of an canvas one or [combined with legend](https://antv.gitbook.io/f2/api/tooltip#combine-legend-and-tooltip).
#### Combine Legend and Tooltip
On mobile, in order to make better use of the screen size, the tooltip and legend are often combined in the chart design. Like this:
In F2, we can use a custom tooltip to implement, see demo and code [here](https://antv.alipay.com/zh-cn/f2/3.x/demo/line/series.html):
```javascript
chart.tooltip({
custom: true, // required
onChange(obj) {
var legend = chart.get('legendController').legends.top[0]; // get the top legend instance
var tooltipItems = obj.items;
var legendItems = legend.items;
var map = {};
legendItems.map(function(item) {
map[item.name] = _.clone(item);
});
tooltipItems.map(function(item) {
var name = item.name;
var value = item.value;
if (map[name]) {
map[name].value = value;
}
});
legend.setItems(_.values(map)); // update legend items
},
onHide: function onHide() {
var legend = chart.get('legendController').legends.top[0];
legend.setItems(chart.getLegendItems().country); // revert the original items of the legend
}
});
```
#### External(HTML) Tooltip
We also can define a html tooltip, like this, see demo and code [here](https://antv.alipay.com/zh-cn/f2/3.x/demo/tooltip/custom.html):
```javascript
chart.tooltip({
custom: true,
showCrosshairs: false,
onChange: function onChange(ev) {
var tooltipEl = $('.f2-tooltip'); // get the tooltip html element
var currentData = ev.items[0];
var text = currentData.value;
tooltipEl.html(['' + currentData.origin.date + '', '' + 'Web Visits: ' + text + ''].join(''));
tooltipEl.css({
opacity: 1,
left: canvasOffsetLeft + currentData.x - tooltipEl.outerWidth() / 2 + 'px',
top: canvasOffsetTop + currentData.y - tooltipEl.outerHeight() - 15 + 'px'
});
},
onHide: function onHide() {
var tooltipEl = $('.f2-tooltip');
tooltipEl.css({
opacity: 0
});
}
});
```
Or Like this, combine with Guide.Html and Tooltip, see demo and code [here](https://antv.alipay.com/zh-cn/f2/3.x/demo/line/customize-tootlip.html):
```javascript
chart.guide().html({
position: ['min', 'max'],
html: '',
offsetY: -22.5
});
chart.tooltip({
showCrosshairs: true,
custom: true,
onChange: function onChange(obj) {
var items = obj.items;
var originData = items[0].origin;
var date = originData.date;
var value = originData.value;
var tag = originData.tag;
$('#tooltipWrapper').width($('#mountNode').width());
$('#tooltipWrapper').css('left', 0);
$('#tooltipName').css('margin-left', 15);
$('#tooltipValue').css('margin-right', 15);
if (tag === 1) {
$('#tooltipName').html(date + '
');
} else if (tag === 2) {
$('#tooltipName').html(date + '
');
} else {
$('#tooltipName').text(date);
}
var color;
if (value >= 0) {
color = '#FA541C';
} else {
color = '#1CAA3D';
}
$('#tooltipValue').html('涨幅：' + items[0].value + '');
$('#tooltipWrapper').show();
},
onHide: function onHide() {
$('#tooltipWrapper').hide();
}
});
```
### More Demos
| Demo | demo |
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
| [HTML tooltip](https://antv.alipay.com/zh-cn/f2/3.x/demo/component/tooltip-custom.html) |  |
| [showTooltip()](https://antv.alipay.com/zh-cn/f2/3.x/demo/component/tooltip-showTooltip.html) |  |
| [styling](https://antv.alipay.com/zh-cn/f2/3.x/demo/component/tooltip-style.html) |  |
| [tooltip with title](https://antv.alipay.com/zh-cn/f2/3.x/demo/component/tooltip-showTitle.html) |  |
| [vertical layout](https://antv.alipay.com/zh-cn/f2/3.x/demo/component/tooltip-layout.html) |  |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://antv.gitbook.io/f2/api/chart/tooltip.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.