Tooltips & Crosshairs

Architecture Overview

The tooltip system is split into two rendering spaces to avoid the most common charting library pitfalls:

• Canvas space — Crosshair lines, snap dots, and band highlights render inside the chart's scene graph. They are part of the canvas frame buffer and are pixel-perfect at any DPR.
• HTML DOM space — The tooltip content box renders in a React Portal attached to document.body. This means it can never be clipped by overflow: hidden on the chart container or any parent element.

A framework-agnostic TooltipStore bridges the two: the canvas engine writes state (active entries, anchor position) and React components subscribe via useSyncExternalStore. Each chart instance gets its own store — multiple charts on the same page never interfere.

Quick Start

Imperative API

Add the tooltip and crosshair keys to your RadiantChartOptions:

import RadiantChart from 'radiant-charts';

<RadiantChart
  options={{
    data: [...],
    series: [{ type: 'bar', xKey: 'month', yKey: 'revenue' }],
    crosshair: { x: true },
    tooltip: {
      shared: true,
      sticky: true,
      positionMode: 'snap-to-data',
      delay: { show: 0, hide: 100 },
    },
  }}
  width="100%"
  height={400}
/>

Declarative API

Use the <Tooltip> config component as a child of <Chart>:

import { Chart, Bar, Line, Tooltip, XAxis, Legend } from 'radiant-charts';

<Chart data={data} crosshair={{ x: true }}>
  <Tooltip mode="shared" sticky snap />
  <XAxis />
  <Legend position="bottom" />
  <Bar xKey="month" yKey="sales" fill="#6366f1" />
  <Line xKey="month" yKey="target" stroke="#f59e0b" />
</Chart>

Tooltip Modes

Shared Mode (default)

In shared mode, hovering any point on the X axis gathers all series values at that X position into a single tooltip. This is the natural choice for line, area, and bar charts where comparing across series is the primary interaction. Each series gets a color swatch and its own value row.

For stacked bar and area charts, the tooltip automatically calculates each segment's percentage of the stack total and displays it alongside the absolute value.

Item Mode

In item mode, only the single hovered element is shown. This is the default for non-cartesian chart types (pie, treemap, gauge, sankey, etc.) and is recommended for scatter plots where aggregation by X value doesn't make semantic sense.

Set tooltip.mode: "item" or tooltip.shared: false.

Positioning

Snap to Data (default)

The tooltip anchors at the resolved data point's pixel position. It stays locked to the data even as the cursor wobbles slightly. Collision detection flips the tooltip to the opposite side if it would overflow the viewport, then shifts it along the cross-axis to keep it fully visible.

Follow Pointer

The tooltip tracks the raw cursor position (clientX/clientY) instead of snapping to data points. Data resolution still happens — the tooltip content always shows the nearest data — but the floating box moves with the mouse. Set tooltip.positionMode: "follow-pointer".

Fixed Position

The tooltip renders at a fixed corner of the chart container and does not move while active. Useful for dashboards where tooltip movement would be distracting. Set tooltip.positionMode: "fixed".

Offset

Fine-tune the distance between the anchor and the tooltip box with tooltip.offset. The y value controls the main axis distance (default: 12px), and x shifts the tooltip along the cross-axis (default: 0).

Crosshairs & Visual Guides

Crosshairs are canvas-native scene graph elements that render in the crosshairGroup layer, between the series and the watermark. They are configured via the top-level crosshair option (not inside tooltip).

Vertical Crosshair

A dashed vertical line from the top to the bottom of the plot area. For BandScale axes (bar, line, area), it snaps to the nearest category center. Set crosshair: { x: true }.

Horizontal Crosshair

A dashed horizontal line tracking the cursor's Y position. Set crosshair: { y: true }.

Band Highlight

When the vertical crosshair is enabled on a BandScale chart, a semi-transparent rectangle highlights the full band behind the active category. This gives clear visual feedback about which category is being inspected.

Series Snap Dots

In shared mode, each series gets a filled circle (snap dot) rendered at its data point for the active X value. Each dot uses the series color with a white stroke halo for contrast. These appear automatically when the shared tooltip is active.

Formatting

Value Formatter

Override how values are displayed with tooltip.valueFormatter. The function receives the raw value and the full TooltipDatumEntry, so you can format differently per series:

tooltip: {
  valueFormatter: (value, entry) => {
    if (entry.seriesId === 'revenue') return '$' + value.toLocaleString();
    if (entry.seriesId === 'convRate') return value.toFixed(1) + '%';
    return String(value);
  }
}

Label Formatter

Customize the series name labels with tooltip.labelFormatter. By default, underscores are replaced with spaces and words are title-cased.

Header Formatter

In shared mode, the tooltip header shows the X-axis value. Use tooltip.headerFormatter to format it (e.g., converting a date string to a human-readable format).

Sorting

Control the order of entries in the shared tooltip with tooltip.sortEntries. Use "desc" for highest-value-first, "asc" for lowest-first, or pass a custom comparator function.

Sticky / Pinning

When tooltip.sticky: true, the tooltip system supports click-to-pin:

• Click a data point to pin the tooltip. It transitions from pointer-events: none to pointer-events: auto, becoming fully interactive.
• Click another data point to move the pin.
• Click empty chart space, press Escape, or click the x close button to unpin.
• While pinned, hovering other data points does not change the tooltip content.

Pinned tooltips are ideal for dashboards where users need to inspect a specific data point, copy values, or interact with embedded controls (buttons, links) inside a custom tooltip render function.

Keyboard Navigation

When the chart container is focused (click the chart or tab to it), the following keyboard shortcuts are available:

Accessibility

The tooltip system is designed with accessibility as a first-class concern:

• The tooltip portal carries role="tooltip" and aria-live="polite" for screen reader announcements.
• A visually-hidden region inside the tooltip announces the active data in plain text (e.g., "Revenue: $91,000 at Jun").
• The chart container has tabindex="0" so it can be focused for keyboard navigation.
• A full data table (<table> with className="sr-only") is rendered in every chart as the canonical accessible data representation.
• Tooltip position transitions respect prefers-reduced-motion.

Touch Device Support

On touch devices, the tooltip system maps touch events to the same handlers used by mouse events:

• touchstart resolves the tooltip at the touch point (equivalent to mousemove).
• touchend pins the tooltip (equivalent to click) — since there's no hover state on touch, a tap reveals and pins in one gesture.
• touchmove updates the tooltip as the finger moves across the chart.

Custom Rendering

Render Prop

Replace the entire tooltip UI by passing a render function to the tooltip options. It receives the full TooltipState object and should return a React node:

tooltip: {
  render: (state) => (
    <div className="my-custom-tooltip">
      <h4>{state.sharedLabel}</h4>
      {state.entries.map(e => (
        <div key={e.seriesId}>
          <span style={{ color: e.color }}>{e.title}</span>: {e.yValue}
        </div>
      ))}
    </div>
  )
}

useChartTooltip() Hook

For maximum control, use the useChartTooltip() hook to build a completely custom tooltip component from scratch. The hook must be used inside a <RadiantChart> or <Chart> component tree:

import { useChartTooltip } from 'radiant-charts';

function MyTooltip() {
  const { active, entries, anchorX, anchorY, pin, unpin } = useChartTooltip();
  if (!active) return null;

  return (
    <div style={{ position: 'fixed', left: anchorX + 16, top: anchorY - 8 }}>
      {entries.map(e => (
        <div key={e.seriesId}>
          {e.title}: {e.yValue}
          <button onClick={() => alert(`Drill into ${e.title}`)}>
            Details
          </button>
        </div>
      ))}
    </div>
  );
}

API Reference

TooltipOptions

Passed via options.tooltip (imperative) or <Tooltip ...props /> (declarative).

CrosshairStyle

When crosshair.x or crosshair.y is an object instead of a boolean, it accepts these properties:

TooltipDatumEntry

Each entry in the tooltip's entries array has this shape. Available in formatters, custom render functions, and the useChartTooltip() hook.

useChartTooltip() Return Value

The useChartTooltip() hook returns a ChartTooltipContext object with the following fields:

Behavior by Chart Type

Cartesian Charts (Bar, Line, Area)

Tooltips snap to the nearest BandScale category center. In shared mode, all series values at that X position are gathered. Stacked charts include automatic percentage computation. Band highlighting fills the category's column.

Scatter & Bubble Charts

Uses 2D nearest-neighbor resolution in pixel space. The hit radius scales with the marker size (minimum 12px). Recommended to use tooltip.mode: "item" since X-axis aggregation rarely makes sense for scatter data.

Pie, Donut & Radial Charts

Non-cartesian charts use the canvas scene graph's built-in hit testing. Hovering a pie slice shows the slice's label, absolute value, and percentage of total. No crosshair lines are drawn — instead, series focus dimming highlights the active slice.

Financial Charts (Candlestick, OHLC)

Item-mode tooltips show Open, High, Low, Close as labeled rows. If SMA/EMA indicators are active, their values are included in the shared tooltip entries. The vertical crosshair snaps to candle centers.

Hierarchical Charts (Treemap, Sunburst, Icicle)

Hit testing via the scene graph identifies the specific node being hovered. The tooltip shows the node's label, value, and its percentage of the parent node.

Network Charts (Sankey, Chord, Force Graph)

Node hover shows the node label and aggregated flow value. Link hover shows the source, target, and flow value. The tooltip anchors at the cursor position since network layouts have no axis system.

Statistical Charts (Boxplot, Violin, Histogram)

Boxplot tooltips show min, Q1, median, Q3, and max. Violin tooltips show distribution statistics. Histogram tooltips show the bin range and count.

Geospatial Charts (Choropleth, Bubble Map)

Region hover shows the region name and data value. The tooltip uses scene-graph hit testing on the rendered map paths.

Edge Cases & Notes

• Empty data: The tooltip system gracefully no-ops. No tooltip or crosshair is shown.
• Single data point: Snap-to-data works — the tooltip always resolves to the one available point.
• Chart resize: The tooltip recalculates its viewport anchor position when the chart resizes. The portal follows the data point, not the old pixel position.
• SSR: All DOM access (document.body, getBoundingClientRect) is gated behind typeof window !== 'undefined' checks. The portal renders null during SSR.
• Multiple charts: Each chart instance has its own TooltipStore. No global state, no cross-contamination.
• Chart destruction: TooltipStore.destroy() removes the portal, cancels timers, and unsubscribes all listeners on unmount.
• Animations: Tooltip opacity transitions use CSS (transition: opacity 0.12s ease). Position changes in snap mode use a short transform transition for smooth gliding. All transitions are suppressed when prefers-reduced-motion: reduce is active.