# @chartist-js/tooltips API

> Every function and type @chartist-js/tooltips exports. Types from `chartist` link to the Chartist API reference.

## tooltips

```ts
function tooltips<R extends keyof NodeRoles = DefaultTooltipRole>(options?: TooltipsOptions<R>): ChartPlugin
```

Shows a tooltip for the values of a chart: under the pointer, under a finger, or in keyboard focus. Points, bars and slices get one by default, with the value's title (its `meta` or label), the series' name and the value; `format` and `render` change the content. The tooltip is a `.ct-tooltip` element in the chart's container, shown in the top layer, so `overflow: hidden` can't clip it, and styled with the `--ct-tooltip-*` properties of `@chartist-js/tooltips/styles.css`. Content is text unless you `render` it, so the plugin works under a strict Content Security Policy and Trusted Types.

The values form one tab stop per chart: arrow keys move between them and `Escape` hides the tooltip. Where a chart has no container (`toScene()`, server rendering), the plugin does nothing.

Parameters:

- `options?: TooltipsOptions<R>`

```ts
import { lineChart } from 'chartist';
import { tooltips } from '@chartist-js/tooltips';
import 'chartist/styles.css';
import '@chartist-js/tooltips/styles.css';

lineChart(
  '#chart',
  {
    labels: ['Mon', 'Tue', 'Wed'],
    series: [{ name: 'Visitors', data: [1200, 1500, 1350] }]
  },
  { plugins: [tooltips()] }
);
```

## DefaultTooltipRole

```ts
type DefaultTooltipRole = 'point' | 'bar' | 'slice'
```

The roles that get tooltips without a `roles` option.

## TooltipItemBase

```ts
interface TooltipItemBase
```

What every tooltip item has, whatever its role.

Properties:

- `seriesIndex?: number` The series' index in the chart's data; absent for a node without one, such as a target line.
- `valueIndex?: number` The value's index in its series; absent for a whole series.
- `value?: unknown` The value: a number, or `{ x, y }` when it has both (a scatter chart's point). Absent for a whole series.
- `meta: unknown` The value's `meta`, or the series' for a slice.
- `series: unknown` The series as given in the data: an array, or an object with `data`.
- `seriesName?: string` The series' `name`, when it has one.
- `label?: string` The value's label: at its index, the slice's own, or a target line's.
- `element: Element` The element drawn for the value.

## TooltipItem

```ts
type TooltipItem<R extends NodeRole = NodeRole> = { [K in R]: TooltipItemBase & { readonly role: K; readonly context: NodeRoles[K]['ctx'] } }[R]
```

The value a tooltip is about: what `format` and `render` get, for the roles in `roles`. Checking `item.role` narrows `item.context` to that role's data context, for Chartist's roles and for the roles other layers declare in `NodeRoles` alike: after `item.role === 'trendLine'`, `item.context.slope` is a number.

## TooltipData

```ts
interface TooltipData
```

The chart's data as `render` gets it: its labels and series, read-only.

Properties:

- `labels: readonly (string | number | Date)[]` The labels as given, or an empty array.
- `series: readonly { … }[]` The series, each with its `values`, and its `name` and `meta` when given.
- `flat?: boolean` The data was one flat series of values, as for pies.

## TooltipsOptions

```ts
interface TooltipsOptions<R extends NodeRole = DefaultTooltipRole>
```

Options of [`tooltips`](https://chartist.dev/packages/tooltips/api/#tooltips). `R` is the roles in `roles`, so `format` and `render` get items of those roles only.

Properties:

- `roles?: readonly R[]` The roles of the nodes that get tooltips: `point`, `bar` and `slice` by default. Any role works, of other layers and plugins too: `line` for a tooltip per series, `trendLine` and `targetLine` of `@chartist-js/essentials`. The default text shows what a node has (a target line's label and value, a trend line's series); for more, read `item.context` in `format` or `render`, where checking `item.role` narrows it to that role's context.
- `format?: (item: TooltipItem<R>) => string | null | undefined` Gives a tooltip's text: line breaks show as line breaks. Return `undefined` to keep the default text for that value (handy when you format some roles only), and `null` or an empty string for no tooltip. The text is also the focused value's accessible name. Without it, a tooltip shows the title (the value's `meta` or its label), the series' name and the value.
- `render?: (content: HTMLElement, item: TooltipItem<R>, data: TooltipData) => void | (() => void)` Fills the tooltip yourself, with DOM nodes or a framework's template: `content` is the tooltip's content element, emptied before each call. Return a function to undo it, such as unmounting a component: it runs before the next call, when the tooltip hides, and on `destroy()`. `format` still decides which values have a tooltip and gives their accessible name; without it, the name is the content's text. Setting HTML strings is your code's business: under Trusted Types, it needs your own policy.
- `numberFormat?: NumberFormatOptions` How the default text formats values, as `Intl.NumberFormat` options in the browser's locale, e.g. `{ style: 'currency', currency: 'CHF' }`.
- `position?: 'element' | 'pointer'` Where the tooltip shows: at the value (`element`) or at the mouse or pen while it moves (`pointer`). Touch and keyboard always use the value.
- `keyboard?: boolean` Makes the values reachable by keyboard: one tab stop per chart, arrow keys between values, `Escape` to hide. `false` leaves the tab order and the chart's elements as they are.
- `className?: string` Extra class names for the tooltip element.