Diagnosing Slow Plotly Scatter Charts: When and How to Switch to scattergl for Large Datasets

Recognizable Condition

When you supply more than ~100,000 points to a scatter trace, the chart may become unresponsive, lag during pan/zoom, or fail to render at all. In the browser console you might see warnings about Maximum call stack size exceeded or high memory usage values.

Cause / Diagnostic Table

Possible Cause	Diagnostic Check	Expected Result
SVG‑based rendering (default scatter)	Inspect trace.type in your data array	Value is "scatter"
Too many points (>100k)	Count trace.x.length (or trace.y.length)	Value > 100,000
Browser main‑thread blocked by SVG DOM	Use console.time('render') before Plotly.newPlot and console.timeEnd('render') after	Render time > 2 s
WebGL not available	Check navigator.getContext('webgl') or navigator.userAgent for legacy browsers	Result is null or IE11 string
Layout reflows due to autosize or dynamic width/height	Look for layout.autosize and CSS that changes container size on interaction	True or CSS trigger

Ordered Checks

1. Verify trace type – open the JavaScript object that defines the trace and confirm type: "scattergl" is used instead of "scatter".
2. Count points – in the console run console.log(trace.x.length) to ensure you are above the 100k threshold.
3. Measure render time – add console.time('render') before Plotly.newPlot and console.timeEnd('render') after to see the difference.
4. Confirm WebGL support – execute console.log(navigator.getContext && navigator.getContext('webgl')). If null, the browser cannot use scattergl.
5. Check layout reflows – temporarily set layout.width and layout.height to fixed numbers (e.g., 800) and disable autosize.

Fixes Tied to Findings

• Switch to scattergl – change type to "scattergl" and ensure you load the WebGL bundle (e.g., plotly-gl-dist or plotly.min.js version ≥ 1.50).
• Downsample or aggregate – reduce the point count to <50k by using LTTB, simple averaging, or a spatial index.
• Set static dimensions – use layout.width: 800, layout.height: 600 and autosize: false to avoid layout thrashing.
• Enable staticPlot – for non‑interactive displays set staticPlot: true to skip expensive interactivity.
• Use hovermode="closest" – reduces the number of hover calculations when many points are present.
• Fallback for unsupported browsers – detect WebGL support and render a simplified scatter trace if unavailable.

Escalation Criteria

If after applying the above fixes the chart still lags or crashes, consider:

• Server‑side rendering or pre‑aggregated tiles (e.g., using Mapbox GL or deck.gl).
• Switching to a dedicated WebGL library such as deck.gl or three.js for extreme data volumes.
• Splitting the dataset into multiple smaller traces and layering them.

Concrete Example

Below is a minimal HTML snippet that demonstrates the performance difference. Replace NUM_POINTS with 250000 to test.

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.plot.ly/plotly-2.22.0.min.js"></script>
</head>
<body>
  <div id="plot"></div>
  <script>
    const NUM_POINTS = 250000;
    const x = Array.from({length: NUM_POINTS}, (_, i) => i);
    const y = Array.from({length: NUM_POINTS}, () => Math.random());

    const trace = {
      x: x,
      y: y,
      mode: 'markers',
      type: 'scattergl', // try changing to 'scatter' to see the slowdown
      marker: {size: 3}
    };

    const layout = {
      width: 800,
      height: 600,
      autosize: false,
      hovermode: 'closest'
    };

    console.time('render');
    Plotly.newPlot('plot', [trace], layout).then(() => console.timeEnd('render'));
  </script>
</body>
</html>

Open the page, open the browser console, and observe the render time. Switching type to scatter should noticeably increase the time and degrade interactivity.

Limitations & Practical Check

• scattergl is only available from Plotly.js 1.50 onward. Older releases will ignore the trace type.
• Internet Explorer 11 and some embedded browsers do not support WebGL; in those cases you must fall back to scatter.
• Large datasets may still cause memory exhaustion on low‑end devices; monitor performance.memory.usedJSHeapSize if available.
• Always test on the target browsers before deploying. Use navigator.getContext('webgl') to confirm support programmatically.