Tooltip

Tooltip component: one box, drawn inside the chart's svg, that follows the pointer and shows what it is over. It renders a list (a title and one row per topic, with a colour dot, the topic's name and its value) for the multi-value charts -- line, stacked area, stacked bar and grouped bar -- or a single value (a title, the element's name and a big value) for the single-value charts -- bar, scatter plot, heatmap and donut. By default it picks the layout from the data point it is given; layout() forces one. miniTooltip is this component with the single layout, an empty title and a .2f number format.

The tooltip keeps itself inside the chart: it measures the svg it is drawn in, sits beside its anchor, flips to the other side when there is no room and slides so it is never cut off. It fades in when shown, fades out when hidden and eases towards each new position.

Every chart dispatches the same three events, so wiring is always chart.on('customMouseOver', tooltip.show).on('customMouseMove', tooltip.update).on('customMouseOut', tooltip.hide). What they carry, and where to .call() the tooltip:

Chart	`customMouseOver`	`customMouseMove`	anchor `[x, y]`	attach to
line, stacked area	`(data, [x, y])`	`(dataPoint, [x, y], [width, height], colorMap)`	the hovered date's x, the pointer's y	`.metadata-group .vertical-marker-container`
stacked bar, grouped bar	`(data, [x, y])`	`(dataPoint, [x, y], [width, height], colorMap)`	the pointer, over a bar only	`.metadata-group`
bar, heatmap, donut	`(dataPoint, [x, y], [width, height])`	`(dataPoint, [x, y], [width, height])`	the pointer, over a shape only	`.metadata-group`
scatter plot	`(dataPoint, [x, y])`	`(dataPoint, [x, y], [width, height])`	the hovered point	`.metadata-group`

Positions are in pixels relative to the chart's drawing area (inside the margins). The chart's size is accepted and ignored: the tooltip measures the chart itself. The line and stacked area charts dispatch nothing while narrower than tooltipThreshold (480 px by default).

miniTooltip, the single-value preset

miniTooltip() is tooltip().layout('single').title('').numberFormat('.2f'): the same component with the single-value layout, no title and a .2f number format, for the bar, scatter plot, heatmap and donut charts. Every accessor documented on this page is available on it.

const barChart = bar(),
    chartTooltip = miniTooltip();

barChart
    .width(500)
    .on('customMouseOver', chartTooltip.show)
    .on('customMouseMove', chartTooltip.update)
    .on('customMouseOut', chartTooltip.hide);

d3Selection.select('.css-selector')
    .datum(dataset)
    .call(barChart);

d3Selection.select('.metadata-group')
    .datum([])
    .call(chartTooltip);

Requires: module:d3-array,
Example

const lineChart = line(),
    chartTooltip = tooltip();

chartTooltip
    .title('Tooltip title');

lineChart
    .width(500)
    .on('customMouseOver', chartTooltip.show)
    .on('customMouseMove', chartTooltip.update)
    .on('customMouseOut', chartTooltip.hide);

d3Selection.select('.css-selector')
    .datum(dataset)
    .call(lineChart);

d3Selection.select('.metadata-group .vertical-marker-container')
    .datum([])
    .call(chartTooltip);

Tooltip
- exports(_selection, _data) ⏏
  - .axisTimeCombinations
  - .dateFormat(_x) ⇒ String | module
  - .dateCustomFormat(_x) ⇒ String | module
  - ~~.dateLabel(_x) ⇒ String | module~~
  - .hide() ⇒ module
  - .locale(_x) ⇒ String | module
  - ~~.nameLabel(_x) ⇒ String | module~~
  - .numberFormat(_x) ⇒ string | module
  - .valueFormatter(_x) ⇒ function | module
  - .shouldShowDateInTitle(_x) ⇒ Boolean | module
  - .show([dataPoint], [position]) ⇒ module
  - .title(_x) ⇒ String | module
  - .tooltipOffset(_x) ⇒ Object | module
  - .layout([_x]) ⇒ String | module
  - .maxEntries([_x]) ⇒ Number | module
  - .topicsOrder(_x) ⇒ Array.<String> | module
  - ~~.topicLabel(_x) ⇒ String | module~~
  - .update(dataPoint, position, [chartSize], [colorMap]) ⇒ module
  - ~~.valueLabel(_x) ⇒ String | module~~
  - .xAxisValueType([_x]) ⇒ String | module

exports(_selection, _data) ⏏

This function creates the graph using the selection as container

Kind: Exported function

Param	Type	Description
_selection	`D3Selection`	A d3 selection that represents the container(s) where the chart(s) will be rendered
_data	`Object`	The data to attach and generate the chart

exports.axisTimeCombinations

constants to be used to force the x axis to respect a certain granularity current options: HOUR_DAY, DAY_MONTH, MONTH_YEAR

Kind: static property of exports
Example

tooltip.dateFormat(tooltip.axisTimeCombinations.HOUR_DAY)

exports.dateFormat(_x) ⇒ `String` | `module`

Exposes the ability to force the tooltip to use a certain date format

Kind: static method of exports
Returns: String | module - Current format or module to chain calls
Access: public

Param	Type	Description
_x	`String`	Desired format

exports.dateCustomFormat(_x) ⇒ `String` | `module`

Exposes the ability to use a custom date format

Kind: static method of exports
Returns: String | module - Current format or module to chain calls
Access: public

Param	Type	Description
_x	`String`	Desired custom format

Example

tooltip.dateFormat(tooltip.axisTimeCombinations.CUSTOM);
tooltip.dateCustomFormat('%H:%M %p')

exports.dateLabel(_x) ⇒ `String` | `module`

Deprecated

Gets or Sets the dateLabel of the data: the field of the data point shown in the title. When the data point has no such field, its key (what the stacked and grouped bar charts dispatch) or its date is used, so the default works for every chart.

Kind: static method of exports
Returns: String | module - Current dateLabel or Chart module to chain calls
Access: public

Param	Type	Description
_x	`String`	Desired dateLabel

exports.hide() ⇒ `module`

Hides the tooltip

Kind: static method of exports
Returns: module - Tooltip module to chain calls
Access: public

exports.locale(_x) ⇒ `String` | `module`

Pass locale for the tooltip to render the date in

Kind: static method of exports
Returns: String | module - Current locale or module to chain calls
Access: public

Param	Type	Description
_x	`String`	Must be a locale tag like 'en-US' or 'fr-FR'

exports.nameLabel(_x) ⇒ `String` | `module`

Deprecated

Gets or Sets the nameLabel of the data

Kind: static method of exports
Returns: String | module - Current nameLabel or Chart module to chain calls
Access: public

Param	Type	Description
_x	`String`	Desired nameLabel

exports.numberFormat(_x) ⇒ `string` | `module`

Gets or Sets the number format for the value displayed on the tooltip

Kind: static method of exports
Returns: string | module - Current numberFormat or Chart module to chain calls
Access: public

Param	Type	Description
_x	`string`	Desired numberFormat for the chart. See examples here

exports.valueFormatter(_x) ⇒ `function` | `module`

Gets or Sets the formatter function for the value displayed on the tooltip. Setting this property makes the tooltip ignore numberFormat.

Kind: static method of exports
Returns: function | module - Current valueFormatter or Chart module to chain calls
Access: public

Param	Type	Description
_x	`function`	Desired formatter function

Example

tooltipChart.valueFormatter(value => value.toString().length.toString())

exports.shouldShowDateInTitle(_x) ⇒ `Boolean` | `module`

Gets or Sets shouldShowDateInTitle

Kind: static method of exports
Returns: Boolean | module - Current shouldShowDateInTitle or Chart module to chain calls
Access: public

Param	Type	Description
_x	`Boolean`	Desired value

exports.show([dataPoint], [position]) ⇒ `module`

Shows the tooltip. Given the hovered data point and its position, as the single-value charts dispatch them on customMouseOver, it renders and places the tooltip at once; otherwise it shows empty until the first update, which is what the multi-value charts need.

Kind: static method of exports
Returns: module - Tooltip module to chain calls
Access: public

Param	Type	Description
[dataPoint]	`Object`	Data point to render
[position]	`Array.<Number>`	[x, y] to anchor the tooltip to, in pixels

exports.title(_x) ⇒ `String` | `module`

Gets or Sets the title of the tooltip (to only show the date, set a blank title)

Kind: static method of exports
Returns: String | module - Current title or module to chain calls
Access: public

Param	Type	Description
_x	`String`	Desired title

exports.tooltipOffset(_x) ⇒ `Object` | `module`

Gets or Sets an offset, in pixels, applied to the point the tooltip is placed next to: x moves the anchor along the chart, y moves the box up (negative) or down. The box still stays inside the chart.

Kind: static method of exports
Returns: Object | module - Current tooltipOffset or module to chain calls
Access: public

Param	Type	Description
_x	`Object`	Object with the x and y offsets

Example

tooltip.tooltipOffset({ x: 0, y: -20 })

exports.layout([_x]) ⇒ `String` | `module`

Gets or Sets the layout: 'list' shows the title and one row per topic, with a colour dot, the topic's name and its value (the multi-value charts: line, stacked area, stacked bar and grouped bar); 'single' shows the title, the name and a big value (the single-value charts: bar, scatter plot, heatmap and donut -- what miniTooltip renders); 'auto', the default, picks by the data point: a list when it carries an array under the topic label, a single value otherwise. Set before the tooltip is drawn.

Kind: static method of exports
Returns: String | module - Current layout or Chart module to chain calls
Access: public

Param	Type	Default	Description
[_x]	`String`	`'auto'`	'auto', 'list' or 'single'

Example

tooltip.layout('single')

exports.maxEntries([_x]) ⇒ `Number` | `module`

Gets or Sets the most rows the tooltip shows. Past that, the last row reads "+n more" instead, so the box keeps a height that fits in the chart. 0 shows every row.

Kind: static method of exports
Returns: Number | module - Current maxEntries or Chart module to chain calls
Access: public

Param	Type	Default	Description
[_x]	`Number`	`12`	Most rows to show

Example

tooltip.maxEntries(6)

exports.topicsOrder(_x) ⇒ `Array.<String>` | `module`

Pass an override for the ordering of your tooltip

Kind: static method of exports
Returns: Array.<String> | module - Current overrideOrder or Chart module to chain calls
Access: public

Param	Type	Description
_x	`Array.<String>`	Array of the names of your tooltip items

exports.topicLabel(_x) ⇒ `String` | `module`

Deprecated

Gets or Sets the topicLabel of the data

Kind: static method of exports
Returns: String | module - Current topicLabel or Chart module to chain calls
Access: public

Param	Type	Description
_x	`String`	Desired topicLabel

exports.update(dataPoint, position, [chartSize], [colorMap]) ⇒ `module`

Updates the content and position of the tooltip. The arguments are what every chart dispatches with customMouseMove, so chart.on('customMouseMove', tooltip.update) is all the wiring needed: the data point, its anchor [x, y] in pixels relative to the chart's drawing area, the chart's size (ignored; the tooltip measures the chart itself) and, from the multi-value charts, the map of topic names to colours. The order the multi-value charts used before 3.0, update(dataPoint, colorMap, x, y), still works and warns once.

Kind: static method of exports
Returns: module - Tooltip module to chain calls
Access: public

Param	Type	Description
dataPoint	`Object`	Data point to render
position	`Array.<Number>`	[x, y] to anchor the tooltip to, in pixels
[chartSize]	`Array.<Number>`	[width, height] of the chart; ignored
[colorMap]	`Object`	Topic name to colour, for the list layout

Example

chart.on('customMouseMove', tooltip.update)

exports.valueLabel(_x) ⇒ `String` | `module`

Deprecated

Gets or Sets the valueLabel of the data

Kind: static method of exports
Returns: String | module - Current valueLabel or Chart module to chain calls
Access: public

Param	Type	Description
_x	`String`	Desired valueLabel

exports.xAxisValueType([_x]) ⇒ `String` | `module`

Gets or Sets how the key of the data point is shown in the title: 'date' formats it as a date, 'number' as a number, 'category' shows it as it is, and 'auto' (the default) picks one per key -- a Date or a string that parses as one is a date, a number or a numeric string is a number, anything else is a category. Set 'date' for keys that happen to parse as numbers, or 'category' for names that happen to parse as dates.

Kind: static method of exports
Returns: String | module - Current xAxisValueType or Chart module to chain calls
Access: public

Param	Type	Default	Description
[_x]	`String`	`'auto'`	'auto', 'date', 'number' or 'category'

Example

tooltip.xAxisValueType('category')

miniTooltip, the single-value preset​

exports(_selection, _data) ⏏​

exports.axisTimeCombinations​

exports.dateFormat(_x) ⇒ String | module​

exports.dateCustomFormat(_x) ⇒ String | module​

exports.dateLabel(_x) ⇒ String | module​

exports.hide() ⇒ module​

exports.locale(_x) ⇒ String | module​

exports.nameLabel(_x) ⇒ String | module​

exports.numberFormat(_x) ⇒ string | module​

exports.valueFormatter(_x) ⇒ function | module​

exports.shouldShowDateInTitle(_x) ⇒ Boolean | module​

exports.show([dataPoint], [position]) ⇒ module​

exports.title(_x) ⇒ String | module​

exports.tooltipOffset(_x) ⇒ Object | module​

exports.layout([_x]) ⇒ String | module​

exports.maxEntries([_x]) ⇒ Number | module​

exports.topicsOrder(_x) ⇒ Array.<String> | module​

exports.topicLabel(_x) ⇒ String | module​

exports.update(dataPoint, position, [chartSize], [colorMap]) ⇒ module​

exports.valueLabel(_x) ⇒ String | module​

exports.xAxisValueType([_x]) ⇒ String | module​

miniTooltip, the single-value preset

exports(_selection, _data) ⏏

exports.axisTimeCombinations

exports.dateFormat(_x) ⇒ `String` | `module`

exports.dateCustomFormat(_x) ⇒ `String` | `module`

exports.dateLabel(_x) ⇒ `String` | `module`

exports.hide() ⇒ `module`

exports.locale(_x) ⇒ `String` | `module`

exports.nameLabel(_x) ⇒ `String` | `module`

exports.numberFormat(_x) ⇒ `string` | `module`

exports.valueFormatter(_x) ⇒ `function` | `module`

exports.shouldShowDateInTitle(_x) ⇒ `Boolean` | `module`

exports.show([dataPoint], [position]) ⇒ `module`

exports.title(_x) ⇒ `String` | `module`

exports.tooltipOffset(_x) ⇒ `Object` | `module`

exports.layout([_x]) ⇒ `String` | `module`

exports.maxEntries([_x]) ⇒ `Number` | `module`

exports.topicsOrder(_x) ⇒ `Array.<String>` | `module`

exports.topicLabel(_x) ⇒ `String` | `module`

exports.update(dataPoint, position, [chartSize], [colorMap]) ⇒ `module`

exports.valueLabel(_x) ⇒ `String` | `module`

exports.xAxisValueType([_x]) ⇒ `String` | `module`