skills/syncfusion-flutter-cartesian-charts/references/tooltip-trackball.md

Tooltip, Trackball & Crosshair

Table of Contents

• Tooltip
• Tooltip Appearance
• Tooltip Format
• Shared Tooltip
• Custom Tooltip Template
• Trackball
• Crosshair

---

Tooltip

Tooltip shows data values when the user taps a data point. Initialize TooltipBehavior in initState — avoid creating it inline in build to prevent recreation on every rebuild.

late TooltipBehavior _tooltip;

@override
void initState() {
  _tooltip = TooltipBehavior(enable: true);
  super.initState();
}

@override
Widget build(BuildContext context) {
  return SfCartesianChart(
    tooltipBehavior: _tooltip,
    series: <CartesianSeries>[
      LineSeries<ChartData, String>(
        enableTooltip: true,
        dataSource: chartData,
        xValueMapper: (d, _) => d.x,
        yValueMapper: (d, _) => d.y,
      ),
    ],
  );
}

TooltipBehavior(enable: true) enables tooltip globally for the chart. enableTooltip: true on a series additionally opts that series in. Both must be set for the tooltip to show.

---

Tooltip Appearance

TooltipBehavior(
  enable: true,
  color: Colors.black87,
  borderColor: Colors.white,
  borderWidth: 1,
  textStyle: const TextStyle(color: Colors.white, fontSize: 12),
  opacity: 0.9,
  duration: 4000,          
  animationDuration: 300,  
  elevation: 4,
  canShowMarker: true,     
  shouldAlwaysShow: false, 
  header: '',              
  shadowColor: Colors.grey,
)

---

Tooltip Format

Use format to customize the tooltip text using placeholders:

TooltipBehavior(
  enable: true,
  format: 'point.x : point.y USD',
)

Examples:

• 'point.x — point.y' → Jan — 35
• 'series.name\nX: point.x\nY: point.y' → multi-line tooltip
• '\$point.y' → $35

---

Shared Tooltip

Show one tooltip that displays values for all series at the same x position simultaneously:

TooltipBehavior(
  enable: true,
  shared: true,
)

---

Custom Tooltip Template

Replace the default tooltip with a completely custom Flutter widget:

TooltipBehavior(
  enable: true,
  builder: (dynamic data, dynamic point, dynamic series, int pointIndex, int seriesIndex) {
    final ChartData chartPoint = data as ChartData;
    return Container(
      padding: const EdgeInsets.all(8),
      decoration: BoxDecoration(
        color: Colors.black87,
        borderRadius: BorderRadius.circular(6),
      ),
      child: Text(
        '${chartPoint.x}: \$${chartPoint.y}',
        style: const TextStyle(color: Colors.white, fontSize: 12),
      ),
    );
  },
)

---

Trackball

The trackball displays a vertical line that snaps to the nearest data point as the user drags across the chart. It's ideal for comparing multiple series at the same x position.

late TrackballBehavior _trackball;

@override
void initState() {
  _trackball = TrackballBehavior(
    enable: true,
    activationMode: ActivationMode.singleTap,
    // Options: singleTap | doubleTap | longPress
    tooltipSettings: const InteractiveTooltip(
      enable: true,
      color: Colors.black,
      textStyle: TextStyle(color: Colors.white),
    ),
    lineType: TrackballLineType.vertical,
    // Options: vertical | none
    lineColor: Colors.grey,
    lineWidth: 1,
    lineDashArray: <double>[5, 5],
    markerSettings: const TrackballMarkerSettings(
      markerVisibility: TrackballVisibilityMode.visible,
      height: 10,
      width: 10,
    ),
    tooltipDisplayMode: TrackballDisplayMode.groupAllPoints,
    // Options: floatAllPoints | groupAllPoints | nearestPoint | none
  );
  super.initState();
}

trackballBehavior: _trackball,

---

Crosshair

The crosshair draws horizontal and vertical lines at the tapped/hovered position, with axis labels showing the exact value at that coordinate.

late CrosshairBehavior _crosshair;

@override
void initState() {
  _crosshair = CrosshairBehavior(
    enable: true,
    activationMode: ActivationMode.singleTap,
    lineType: CrosshairLineType.both,
    // Options: horizontal | vertical | both | none
    lineColor: Colors.grey,
    lineWidth: 1,
    lineDashArray: <double>[5, 5],
    shouldAlwaysShow: false,
  );
  super.initState();
}

crosshairBehavior: _crosshair,

---

Choosing Between Tooltip, Trackball, and Crosshair

Need	Use
Show value on tap of a single point	TooltipBehavior
Compare all series values at an x position	TrackballBehavior
Show exact x/y coordinates at cursor/finger	CrosshairBehavior
Show a custom overlay widget	TooltipBehavior with builder