Add scroll capture functionality to WebAgg backend (#30403)

ianhi · web-flow · commit a0fa8112e51a · 2025-08-21T14:47:01.000-04:00
* Add scroll capture functionality to WebAgg backend

* lint
diff --git a/doc/users/next_whats_new/webagg_capture_scroll.rst b/doc/users/next_whats_new/webagg_capture_scroll.rst
@@ -0,0 +1,7 @@
+WebAgg scroll capture control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The WebAgg backend now provides the ability to capture scroll events to prevent
+page scrolling when interacting with plots. This can be enabled or disabled via
+the new `.FigureCanvasWebAggCore.set_capture_scroll` and
+`.FigureCanvasWebAggCore.get_capture_scroll` methods.
diff --git a/lib/matplotlib/backends/backend_webagg_core.py b/lib/matplotlib/backends/backend_webagg_core.py
@@ -178,6 +178,9 @@ def __init__(self, *args, **kwargs):
         # Track mouse events to fill in the x, y position of key events.
         self._last_mouse_xy = (None, None)
 
+        # Control whether scroll events prevent default browser behavior
+        self._capture_scroll = False
+
     def show(self):
         # show the figure window
         from matplotlib.pyplot import show
@@ -224,6 +227,28 @@ def set_image_mode(self, mode):
             self._current_image_mode = mode
             self.handle_send_image_mode(None)
 
+    def set_capture_scroll(self, capture):
+        """
+        Set whether the scroll events on the canvas will scroll the page.
+
+        Parameters
+        ----------
+        capture : bool
+        """
+        if self._capture_scroll != capture:
+            self._capture_scroll = capture
+            self.send_event("capture_scroll", capture_scroll=capture)
+
+    def get_capture_scroll(self):
+        """
+        Get whether scroll events are currently captured by the canvas.
+
+        Returns
+        -------
+        bool
+        """
+        return self._capture_scroll
+
     def get_diff_image(self):
         if self._png_is_old:
             renderer = self.get_renderer()
@@ -335,6 +360,8 @@ def handle_refresh(self, event):
             # Normal toolbar init would refresh this, but it happens before the
             # browser canvas is set up.
             self.toolbar.set_history_buttons()
+        # Send the current capture_scroll state to newly connected clients
+        self.send_event('capture_scroll', capture_scroll=self._capture_scroll)
         self.draw_idle()
 
     def handle_resize(self, event):
diff --git a/lib/matplotlib/backends/web_backend/js/mpl.js b/lib/matplotlib/backends/web_backend/js/mpl.js
@@ -24,6 +24,8 @@ mpl.figure = function (figure_id, websocket, ondownload, parent_element) {
 
     this.supports_binary = this.ws.binaryType !== undefined;
 
+    this.capture_scroll = false;
+
     if (!this.supports_binary) {
         var warnings = document.getElementById('mpl-warnings');
         if (warnings) {
@@ -313,6 +315,9 @@ mpl.figure.prototype._init_canvas = function () {
         } else {
             event.step = -1;
         }
+        if (fig.capture_scroll) {
+            event.preventDefault();
+        }
         on_mouse_event_closure('scroll')(event);
     });
 
@@ -524,6 +529,10 @@ mpl.figure.prototype.handle_navigate_mode = function (fig, msg) {
     }
 };
 
+mpl.figure.prototype.handle_capture_scroll = function (fig, msg) {
+    fig.capture_scroll = msg['capture_scroll'];
+};
+
 mpl.figure.prototype.updated_canvas_event = function () {
     // Called whenever the canvas gets updated.
     this.send_message('ack', {});
