# Tooltip

> An interactive tooltip component for charts with crosshair, dots, date picker, and customizable content

Source: https://ui.cortexcn.dev/docs/utility/tooltip

## Installation

```bash
npx shadcn@latest add @cortexcn/chart-tooltip
```

## Usage

The ChartTooltip component provides hover interactions for charts. It must be used inside a chart component (`LineChart`, `AreaChart`, `BarChart`).

```tsx
import { LineChart, Line, Grid, ChartTooltip } from "@/components/charts";

<LineChart data={data}>
  <Grid horizontal />
  <Line dataKey="value" />
  <ChartTooltip />
</LineChart>;
```

## Props

| Prop                  | Type                                     | Default                           | Description                                                                                   |
| --------------------- | ---------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------- |
| `showDatePill`        | `boolean`                                | `true`                            | Show animated date ticker at bottom                                                           |
| `showCrosshair`       | `boolean`                                | `true`                            | Show vertical crosshair line                                                                  |
| `showDots`            | `boolean`                                | `true`                            | Show dots on data points                                                                      |
| `indicatorColor`      | `string \| (point) => string`            | —                                 | Crosshair and dot color; pass a function for dynamic colors                                   |
| `indicatorDasharray`  | `string`                                 | —                                 | SVG dash pattern for the crosshair (e.g. `"4,4"`). Omit for solid                             |
| `indicatorFadeEdges`  | `"both" \| "top" \| "bottom" \| "none"`  | `"both"`                          | Vertical crosshair fade; `none` = solid line                                                  |
| `indicatorFadeLength` | `number`                                 | `10`                              | Fade zone size (% of crosshair height) when fading                                            |
| `matchCrosshair`      | `boolean`                                | `false`                           | When `true`, the panel uses the crosshair spring and moves in sync                            |
| `damping`             | `number`                                 | `20`                              | Panel follow damping (default). `0` = instant. Ignored when `matchCrosshair` is `true`        |
| `springConfig`        | `{ stiffness: number; damping: number }` | chart config                      | Full spring override for crosshair, dots, and date pill                                       |
| `boxSpringConfig`     | `{ stiffness: number; damping: number }` | chart config                      | Full spring override for the floating tooltip panel                                           |
| `backgroundColor`     | `string`                                 | `var(--chart-tooltip-background)` | Panel background (CSS variable or color value)                                                |
| `panelStyle`          | `CSSProperties`                          | —                                 | Inline styles for tooltip background and blur                                                 |
| `dotVariant`          | `"dot" \| "ring"`                        | `"dot"`                           | Dot style on series markers                                                                   |
| `dotRadiusFraction`   | `number`                                 | —                                 | Ring corner radius as a fraction of side length (0 = square, 0.5 = circle). Ring variant only |
| `dotScale`            | `number`                                 | `1`                               | Size multiplier for ring indicators. Ring variant only                                        |
| `dotStrokeWidth`      | `number`                                 | `1.5`                             | Ring stroke width in pixels. Ring variant only                                                |
| `dotColor`            | `string \| (point, line) => string`      | —                                 | Override dot/ring color (e.g. when fill is gradient/pattern)                                  |
| `content`             | `(props) => ReactNode`                   | -                                 | Custom content renderer                                                                       |
| `rows`                | `(point) => TooltipRow[]`                | -                                 | Custom row generator                                                                          |
| `children`            | `ReactNode`                              | -                                 | Additional content (e.g., markers)                                                            |
| `className`           | `string`                                 | `""`                              | Additional CSS class                                                                          |

### TooltipRow Interface

```ts
interface TooltipRow {
  color: string; // Dot color
  label: string; // Row label
  value: string | number; // Display value
}
```

## Anatomy

The tooltip has several visual components:

1. **Crosshair** - Vertical line that follows the cursor
2. **Dots** - Circles on each data point at the hovered position
3. **Tooltip Box** - Content panel with title and rows
4. **Date Pill** - Animated date ticker at the bottom

Each component can be shown/hidden independently.

## Examples

### Default Tooltip

Full-featured tooltip with crosshair, dots, and date pill.

### Solid crosshair

Remove vertical fade with `indicatorFadeEdges="none"` for a flat crosshair line.

### Crosshair fade

Fade the crosshair from the top, bottom, both ends, or not at all. Use `indicatorFadeLength` to control how far the fade extends (percentage of chart height).

### Dashed crosshair

Pass an SVG dash pattern to `indicatorDasharray`.

### Match crosshair

By default the tooltip panel eases independently with `damping={20}`. Set `matchCrosshair` to lock the panel to the crosshair spring.

### Panel damping

The default panel uses `damping={20}` without any props. Increase `damping` for heavier lag, or set `damping={0}` for instant follow.

### Crosshair Only

Minimal tooltip with just the crosshair line and tooltip box.

### Minimal (Box Only)

Just the tooltip content box, no visual indicators.

### Custom Row Labels

Use the `rows` prop to customize row labels and value formatting.

### With Bar Chart

The tooltip adapts to bar charts, showing category names instead of dates.

### Fully Custom Content

Use the `content` prop for complete control over the tooltip layout.

## Animation

The tooltip features smooth animations:

- **Tooltip panel** - By default the panel eases with `damping={20}`. Set `matchCrosshair` to share the crosshair spring, or tune lag with `damping` (`0`–`100`) or `boxSpringConfig`.
- **Crosshair** - Spring physics for snappy following (`springConfig`)
- **Crosshair style** - Solid by default; pass `indicatorDasharray="4,4"` (or any SVG dash pattern) for a dashed line.
- **Tooltip Box** - Scale/fade animation with flip detection (`boxSpringConfig`)
- **Date Pill** - Slot machine-style number animation
- **Dots** - Fade in/out with the tooltip

All animations use motion/react for fluid, natural movement.

```tsx
<ChartTooltip
  indicatorDasharray="6,4"
  damping={60}
  indicatorColor="var(--chart-2)"
/>
```

## Theming

The tooltip uses CSS variables for theming:

```css
:root {
  --chart-background: oklch(1 0 0);
  --chart-crosshair: oklch(0.4 0.1828 274.34);
}

.dark {
  --chart-background: oklch(0.145 0 0);
  --chart-crosshair: oklch(0.45 0 0);
}
```

The tooltip box itself uses a semi-transparent dark background with blur for universal readability.