Tooltip System API Reference

The Velo Plot features a high-performance, customizable tooltip system designed for scientific data visualization. It supports multiple tooltip types, professional themes, and extensible templates.

Quick Start

The tooltip system is provided by the PluginTools module. You must load this plugin to enable tooltips.

import { createChart } from 'velo-plot';
import { PluginTools } from 'velo-plot/plugins/tools';

const chart = createChart({
  container: document.getElementById('chart')
});

// Load the plugin to enable tooltips and analysis tools
await chart.use(PluginTools({
  useEnhancedTooltips: true,
  tooltipConfig: {
    theme: 'glass',
    showDelay: 100,
    followCursor: true
  }
}));

Alternatively, if you provide tooltip options during createChart, they will be automatically applied as soon as PluginTools is loaded via chart.use().

const chart = createChart({
  container,
  tooltip: { theme: 'midnight' } // Queued until plugin is loaded
});

await chart.use(PluginTools()); // Queued config is applied now

Tooltip Options

The system is configured via the tooltip property in ChartOptions.

Property	Type	Default	Description
enabled	boolean	true	Globally enable/disable tooltips.
theme	TooltipThemeName | Partial<TooltipTheme>	'dark'	Visual style of the tooltips.
showDelay	number	50	Delay in ms before showing a tooltip.
hideDelay	number	100	Delay in ms before hiding a tooltip.
followCursor	boolean	false	Whether the tooltip should follow the mouse.
dataPoint	DataPointTooltipOptions	-	Configuration for point-hover tooltips.
crosshair	CrosshairTooltipOptions	-	Configuration for multi-series vertical tooltips.
heatmap	HeatmapTooltipOptions	-	Configuration for heatmap cell tooltips.
annotation	AnnotationTooltipOptions	-	Configuration for annotation hovers.
range	RangeTooltipOptions	-	Configuration for range statistics.

DataPointTooltipOptions

Property	Type	Default	Description
enabled	boolean	true	Enable tooltips on individual points.
snapToPoint	boolean	true	Snap the tooltip to the nearest data point.
hitRadius	number	20	Hotspot radius in pixels for detection.
templateId	string	'default'	Template to use for rendering.

Built-in Templates

Choose the right template for your data visualization needs:

• 'default': Professional multi-line display with series indicator and header.
• 'minimal': Compact single-line values for high-density charts.
• 'scientific': High-precision unicode notation (e.g., 6.022 × 10²³).
• 'crosshair': Optimized for vertical tracking across multiple series.
• 'heatmap': Specialized for Z-values with color swatches and scales.
• 'annotation': Displays labels and values for markers, lines, and bands.
• 'range': Rich statistical summary (min, max, mean, count) for data regions.

Built-in Themes

• 'dark': Elegant dark theme (default).
• 'light': Clean professional light theme.
• 'glass': Modern translucent design with backdrop blur.
• 'midnight': Deep blue tones for dark mode enthusiasts.
• 'electrochemistry': High-contrast scientific UI with mono fonts.
• 'neon': Vibrant glowing effect.
• 'minimal': Ultra-compact for high-density dashboards.

Custom Templates

You can create custom templates by implementing the TooltipTemplate interface and registering it with the manager.

class MyTemplate implements TooltipTemplate<DataPointTooltip> {
  id = 'my-custom';
  supportedTypes = ['datapoint'];

  measure(ctx, data, theme) {
    return { width: 100, height: 50, padding: theme.padding };
  }

  render(ctx, data, position, theme) {
    ctx.fillStyle = 'red';
    ctx.fillRect(position.x, position.y, 100, 50);
  }
}

chart.tooltip.registerTemplate('my-custom', new MyTemplate());

Programmatic Control

You can control tooltips via the chart.tooltip API.

// Show a manual tooltip
chart.tooltip.show({
  type: 'datapoint',
  seriesId: 'main',
  seriesName: 'Sensor A',
  dataX: 10.5,
  dataY: 42.1,
  pixelX: 200,
  pixelY: 150
}, { duration: 3000 });

// Hide all tooltips
chart.tooltip.hideAll();

// Change configuration (SAFE: can be called immediately after createChart, 
// settings are queued and applied once the plugin is active)
chart.tooltip.configure({ theme: 'midnight' });

Performance Tips

1. Snap to Point: Enabling snapToPoint is efficient as it uses the chart's optimized hit-testing.
2. Templates: Use simple templates for very dense data.
3. Themes: Themes with backdropBlur (like glass) are more GPU-intensive on some browsers.

Known limitations

• Bundle entry — pick velo-plot, velo-plot/trading, velo-plot/scientific, or velo-plot/full. See Bundle Architecture.
• WebGPU renderer (renderer: 'webgpu') requires an extended bundle entry and is experimental — use WebGL (default) for production.
• SVG — exportSVG() and renderer: 'svg' require an extended bundle. LaTeX labels and contour overlays are partial; 3D is not supported in SVG. See SVG examples.
• See Plugin status registry for plugin maturity (complete, partial, experimental).