# Tooltip (/docs/charts/building-blocks/tooltip)

Use `.Tooltip` to show the values at the point a reader hovers or inspects with the keyboard. It lists each series with its label, color and formatted value from [Series Config](./series-config.mdx), and stays inside the plot.

<Example caption="Hover a day, or focus the chart and press the arrow keys, to see both response times.">
<Basic />

```tsx
"use client";

import { BarChart, type SeriesConfig, TooltipContent } from "@kind-ui/charts";

const data = [
  { day: "Mon", p50: 120, p95: 340 },
  { day: "Tue", p50: 132, p95: 365 },
  { day: "Wed", p50: 118, p95: 310 },
  { day: "Thu", p50: 141, p95: 402 },
  { day: "Fri", p50: 126, p95: 355 },
];

const milliseconds = (value: unknown) => `${value} ms`;

const config = {
  p50: { label: "Median", color: "#3659b8", formatValue: milliseconds },
  p95: { label: "95th percentile", color: "#c2410c", formatValue: milliseconds },
} satisfies SeriesConfig;

export default function ResponseTimeChart() {
  return (
    <BarChart data={data} config={config} aria-label="Response time by day">
      <BarChart.Grid />
      <BarChart.XAxis dataKey="day" />
      <BarChart.YAxis width={40} />
      <BarChart.Series dataKey="p50" />
      <BarChart.Series dataKey="p95" />
      <BarChart.Tooltip
        content={(tooltip) => <TooltipContent tooltip={tooltip} indicator="dot" />}
      />
    </BarChart>
  );
}
```
</Example>

## Usage [#usage]

### Values [#values]

The tooltip shows a row for each series at the inspected point, in the order the series are drawn, with the value `formatValue` returns. A missing or `null` value shows "No data", unless every row is missing, in which case no tooltip appears. When a series is dimmed or hidden, its row stays, dimmed. Press Escape to dismiss it.

Pass `valueAnimation="shuffle"` to roll the digits of numeric values as they change. It stays still when the reader prefers reduced motion.

### Custom Content [#custom-content]

Pass a `content` function to render the tooltip yourself. To keep the labels, colors and formats, return `TooltipContent` and pass the function's props through as `tooltip`, as the example does. `TooltipContent` takes the marker's shape as `indicator` (`line` by default, `dot` or `dashed`), and `hideLabel` or `hideIndicator` to drop the heading or the marker.

### Categories [#categories]

When a row's config key isn't its `dataKey`, like a category ID in a pie, pass `itemKey` to return the key for each row. Pass `normalizedValue` to show each value as a percentage of its total next to the raw value, as stacked charts do.

### Size [#size]

The tooltip grows up to `maxWidth` (180px by default) and never past the plot; content that doesn't fit scrolls. Use `frameProps` for the attributes and styles of the element that positions it.

## API Reference [#api-reference]

### Tooltip [#tooltip]

### TooltipOptions

| Prop               | Type                                                                                                                    | Description                                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `frameProps?`      | `Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "children" \| "ref"> \| undefined` | Attributes, styles and handlers for the element that positions the tooltip.                               |
| `maxWidth?`        | `number \| undefined`                                                                                                   | The widest the tooltip grows, in pixels. It never grows wider than the plot. Default: `180`               |
| `itemKey?`         | `((entry: EngineContentProps["payload"][number]) => string) \| undefined`                                               | Returns the config key for a tooltip row, when it isn't the row's `dataKey`, like a category ID.          |
| `normalizedValue?` | `NormalizedValue \| undefined`                                                                                          | Shows each value as a percentage of its total next to the raw value. Applies to the default content only. |
| `valueAnimation?`  | `"shuffle"`                                                                                                             | `"shuffle"` rolls the digits of numeric values as they change. Applies to the default content only.       |

### TooltipContent [#tooltipcontent]

### TooltipContentOptions

| Prop               | Type                                                                                | Description                                                                                  |
| ------------------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `tooltip`          | `UpstreamTooltipContentProps`                                                       | The props your `content` callback receives. Pass them all through.                           |
| `missingValue?`    | `ReactNode`                                                                         | Shown in place of a `null` or missing value. Default: `"No data"`                            |
| `normalizedValue?` | `NormalizedValue \| undefined`                                                      | Shows each value as a percentage of its total next to the raw value.                         |
| `isProjected?`     | `((entry: UpstreamTooltipContentProps["payload"][number]) => boolean) \| undefined` | Marks a row as projected, like a forecast bar. Use the same test you pass to the bar series. |
| `projectedLabel?`  | `ReactNode`                                                                         | Text added after a projected row's value. Default: `"Projected"`                             |
| `valueAnimation?`  | `"shuffle"`                                                                         | `"shuffle"` rolls the digits of numeric values as they change. Off by default.               |
| `hideLabel?`       | `boolean \| undefined`                                                              | Hides the heading. Series labels and values stay. Default: `false`                           |
| `hideIndicator?`   | `boolean \| undefined`                                                              | Hides the color marker, including a configured `icon`. Default: `false`                      |
| `indicator?`       | `"dashed" \| "dot" \| "line"`                                                       | The color marker's shape. A configured `icon` replaces it. Default: `"line"`                 |
| `itemKey?`         | `((entry: UpstreamTooltipContentProps["payload"][number]) => string) \| undefined`  | Returns the config key for a row, when it isn't the row's `dataKey`, like a category ID.     |

<Caption>
`.Tooltip` also takes the props of Recharts' [Tooltip](https://recharts.github.io/en-US/api/Tooltip/), like `formatter` and `labelFormatter`. Scatter, Heatmap and Sankey charts have tooltips of their own; see their chart pages.
</Caption>