ECharts Tooltip: Always Show Exact X, Conditionally Show Y

To make your ECharts tooltip always show the exact X value under the cursor with free axisPointer movement, set trigger: 'axis' and axisPointer: { type: 'line', snap: false }—this prevents snapping to data points and lets the pointer glide anywhere along the X-axis. For conditional Y display, rely on a custom formatter function that checks for real or interpolated data at that X position, hiding Y when there’s none (like gaps or future sections). Your current approach nails it; there’s no simpler native API for conditional Y, but the formatter is ECharts’ built-in powerhouse for this, as seen in official test examples and community patterns.

Contents

• ECharts Tooltip Basics
• Free AxisPointer Movement with snap: false
• Custom Formatter for Conditional Y Values
• Interpolating Data for Smooth Tooltips
• Common Pitfalls and Fixes
• Is a Feature Request Worth It?
• Sources
• Conclusion

ECharts Tooltip Basics

Ever hovered over an ECharts line chart and wished the tooltip just… worked intuitively? Tooltips in ECharts are dead simple at first glance, but they pack serious customization under the hood. The key is trigger, which decides what sparks the popup: 'item' for data points, or 'axis' for the whole axis line. For your setup—tracking along the X-axis regardless of data points—'axis' is non-negotiable. It grabs the precise axisValue (your X coord) every time the cursor moves.

Why does this matter for free movement? With 'axis', the tooltip follows the axisPointer, not just dots on your line. Stack Overflow threads like this one on line chart tooltips hammer home that 'item' flops for continuous tracking. Pair it with axisPointer: { type: 'line' } for that vertical guide line, and you’re golden. But hold up—what about snapping?

Free AxisPointer Movement with snap: false

Snapping is the villain here. By default, on value or time axes, the axisPointer might latch onto the nearest data point. Not what you want when hovering empty space or future timestamps. Flip snap: false in axisPointer, and it floats freely. Boom—cursor at any X, tooltip shows that exact position.

Check the ECharts test file for axisPointer; it demos snap: false explicitly for this “free-moving” vibe. Community docs like ipecharts axisPointer reference confirm: on time/value axes, false means no auto-snapping, perfect for gaps. And this GitHub issue clarifies it works smoothly unless you’re on category axes (which snap implicitly).

Your code already has it: axisPointer: { type: 'line', snap: false }. Test it—drag across no-data zones. X stays precise, no jumping.

Custom Formatter for Conditional Y Values

Here’s the magic: ECharts hands you params in the formatter, packed with axisValue (X) and potential series data. But for conditional Y? No magic switch like showYIfData: true. Instead, craft a formatter callback that inspects the position.

Like your snippet:

formatter: (params) => {
 const x = params[0].axisValue; // Always exact X
 const y = getYAtX(x); // Your interp logic or null check

 let html = `<strong>X: ${formatX(x)}</strong><br/>`;
 if (y !== null && !isNaN(y)) {
 html += `<strong>Y: ${y.toFixed(2)}</strong>`;
 }
 // No Y? Just X. Clean.
 return html;
}

This is straight from the playbook. A Stack Overflow answer on formatters spells it out: “use a callback function for formatter property and access all the related data.” Even Java examples via Tabnine echo trigger: 'axis' + formatter. When no data matches, params[0].data might be undefined—your null check handles it.

Short and sweet: always render X, append Y conditionally. Users see a tooltip persist (good UX), but no fake Ys cluttering gaps.

Interpolating Data for Smooth Tooltips

Gaps in your line? Or future X beyond last point? Don’t leave users hanging—interpolate Y on the fly. Your interpolateY(x) is spot on. Grab nearest points left/right of X, linear interp 'em.

Quick example:

function interpolateY(targetX) {
 const data = yourSeriesData; // [{x: 1, y: 10}, {x: 3, y: 20}, ...]
 let left = null, right = null;
 
 for (let i = 0; i < data.length - 1; i++) {
 if (data[i].x <= targetX && data[i+1].x >= targetX) {
 left = data[i]; right = data[i+1];
 break;
 }
 }
 
 if (left && right) {
 const ratio = (targetX - left.x) / (right.x - left.x);
 return left.y + (right.y - left.y) * ratio;
 }
 return null; // No interp span? Hide Y.
}

For “real” data, check if targetX exactly matches a point (within epsilon). This keeps tooltips honest—interpolated feels real, but gaps stay bare. Ties back to formatter: Y only if interp succeeds.

Common Pitfalls and Fixes

Bumps you’ll hit? Formatter fires on every mouse move—keep it lightweight, or perf tanks. Cache interp results if data’s static.

Trigger mix-ups: 'item' ignores gaps entirely. Stick to 'axis'. Also, time axes? Format axisValue nicely: new Date(x).toLocaleString().

No Y showing even with data? Log params—data might be sparse. NiceGUI discussion shows appending units or decimals via formatter, same idea.

Test edge: future X. Interp fails post-last-point? Null it out. Past first? Same. Users love persistent X for scanning timelines.

Is a Feature Request Worth It?

Native conditionalY or showValueIfData? Tempting, yeah—your use case screams common (gappy time series, forecasts). But formatter covers it robustly already. Release notes for 5.3 added valueFormatter, great for basics, but skips conditionals.

File one? Sure, if you’re in deep. GitHub issues like axisPointer snapping get traction. Pitch: “tooltip.axisPointer.conditionalValue for series presence.” Community examples, like this mailing list snippet, already hack it your way. Until then, formatter reigns.

Sources

1. Apache ECharts tooltip-axisPointer test
2. Stack Overflow: Custom formatter for ECharts tooltip
3. ECharts GitHub: AxisPointer snapping discussion
4. ipecharts axisPointer docs
5. ECharts mailing list: snap: false with formatter
6. Stack Overflow: Line chart tooltip trigger
7. NiceGUI: Tooltip and axisLabel formatting
8. ECharts 5.3 release notes

Conclusion

Stick with your snap: false + custom formatter setup—it’s the ECharts-native path for free-moving axisPointers, persistent X display, and smart conditional Ys via interpolation checks. No simpler API exists yet, but this scales beautifully for real-world charts with gaps. Tweak the interp logic for your data, test those edges, and you’ve got pro-level tooltips that users actually use. Feature request? Go for it if patterns like yours pop up often.