fix: preserve scroll position of all scrollable elements after hot-swap (#23722)

Capture and restore scroll positions of all scrollable elements during hot-swap UI refresh and full page reload. Elements are identified by CSS selector paths built from nth-of-type selectors anchored to the nearest ancestor with an ID, so elements without explicit IDs are also supported. The window scroll position uses a special __window__ key. Only elements with non-zero scroll are captured, keeping the snapshot small.

Both code paths are updated: the vaadin-dev-tools TypeScript (used for dev server WebSocket-triggered refreshes and full reloads via sessionStorage) and the Hotswapper Java inline JS (used for the vaadin-refresh-ui custom event).

Fixes #20371

Author: Artur-

flow-tests/test-live-reload/src/main/java/com/vaadin/flow/uitest/ui/ScrollPositionLiveReloadView.java

@@ -0,0 +1,112 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.uitest.ui;
+
+import com.vaadin.flow.component.html.Div;
+import com.vaadin.flow.component.html.NativeButton;
+import com.vaadin.flow.component.html.Span;
+import com.vaadin.flow.internal.BrowserLiveReload;
+import com.vaadin.flow.internal.BrowserLiveReloadAccessor;
+import com.vaadin.flow.router.Route;
+import com.vaadin.flow.server.VaadinService;
+import com.vaadin.flow.uitest.servlet.ViewTestLayout;
+
+@Route(value = "com.vaadin.flow.uitest.ui.ScrollPositionLiveReloadView", layout = ViewTestLayout.class)
+public class ScrollPositionLiveReloadView extends AbstractLiveReloadView {
+
+    public ScrollPositionLiveReloadView() {
+        // Button to trigger full-refresh (DOM patching, no full page reload)
+        NativeButton refreshButton = new NativeButton(
+                "Trigger UI Refresh (DOM patch)");
+        refreshButton.addClickListener(e -> {
+            BrowserLiveReloadAccessor liveReloadAccess = VaadinService
+                    .getCurrent().getInstantiator()
+                    .getOrCreate(BrowserLiveReloadAccessor.class);
+            BrowserLiveReload browserLiveReload = liveReloadAccess
+                    .getLiveReload(VaadinService.getCurrent());
+            browserLiveReload.refresh(true);
+        });
+        refreshButton.setId("refresh-button");
+        add(refreshButton);
+
+        // Button to trigger full page reload
+        NativeButton reloadButton = new NativeButton(
+                "Trigger Full Page Reload");
+        reloadButton.addClickListener(e -> {
+            BrowserLiveReloadAccessor liveReloadAccess = VaadinService
+                    .getCurrent().getInstantiator()
+                    .getOrCreate(BrowserLiveReloadAccessor.class);
+            BrowserLiveReload browserLiveReload = liveReloadAccess
+                    .getLiveReload(VaadinService.getCurrent());
+            browserLiveReload.reload();
+        });
+        reloadButton.setId("reload-button");
+        add(reloadButton);
+
+        // Outer scrollable container
+        Div outerScroll = new Div();
+        outerScroll.setId("outer-scroll");
+        outerScroll.getStyle().set("height", "400px");
+        outerScroll.getStyle().set("overflow", "auto");
+        outerScroll.getStyle().set("border", "2px solid blue");
+
+        // Inner scrollable container nested inside outer (no ID, to test
+        // scroll restoration for elements identified by DOM path)
+        Div innerScroll = new Div();
+        innerScroll.getStyle().set("height", "200px");
+        innerScroll.getStyle().set("overflow", "auto");
+        innerScroll.getStyle().set("border", "2px solid red");
+        innerScroll.getStyle().set("margin", "10px");
+
+        // Items inside the inner scrollable container
+        for (int i = 0; i < 50; i++) {
+            Div item = new Div();
+            item.setText("Inner item " + i);
+            item.setId("inner-item-" + i);
+            item.getStyle().set("padding", "8px");
+            item.getStyle().set("border-bottom", "1px solid #eee");
+            innerScroll.add(item);
+        }
+
+        outerScroll.add(innerScroll);
+
+        // More items in the outer scrollable container (after the inner one)
+        for (int i = 0; i < 50; i++) {
+            Div item = new Div();
+            item.setText("Outer item " + i);
+            item.setId("outer-item-" + i);
+            item.getStyle().set("padding", "8px");
+            item.getStyle().set("border-bottom", "1px solid #ddd");
+            outerScroll.add(item);
+        }
+
+        add(outerScroll);
+
+        // Items below the scrollable containers for window-level scroll
+        for (int i = 0; i < 100; i++) {
+            Div item = new Div();
+            item.setText("Item " + i);
+            item.setId("item-" + i);
+            item.getStyle().set("padding", "10px");
+            item.getStyle().set("border-bottom", "1px solid #ccc");
+            add(item);
+        }
+
+        Span bottomMarker = new Span("Bottom of page");
+        bottomMarker.setId("bottom-marker");
+        add(bottomMarker);
+    }
+}

flow-tests/test-live-reload/src/test/java/com/vaadin/flow/uitest/ui/ScrollPositionLiveReloadIT.java

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2000-2026 Vaadin Ltd.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not
+ * use this file except in compliance with the License. You may obtain a copy of
+ * the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+ * License for the specific language governing permissions and limitations under
+ * the License.
+ */
+package com.vaadin.flow.uitest.ui;
+
+import net.jcip.annotations.NotThreadSafe;
+import org.junit.Assert;
+import org.junit.Test;
+import org.openqa.selenium.By;
+
+@NotThreadSafe
+public class ScrollPositionLiveReloadIT extends AbstractLiveReloadIT {
+
+    // Inner scroll container has no ID — found by CSS selector to verify
+    // scroll restoration works for elements identified by DOM path
+    private static final String INNER_SCROLL_SELECTOR = "#outer-scroll > div:nth-of-type(1)";
+
+    @Test
+    public void scrollPositionPreservedAfterUIRefresh() {
+        open();
+        waitForElementPresent(By.id("item-50"));
+
+        scrollAllContainers();
+
+        int windowScrollBefore = getScrollY();
+        int outerScrollBefore = getScrollTop("#outer-scroll");
+        int innerScrollBefore = getScrollTop(INNER_SCROLL_SELECTOR);
+
+        Assert.assertTrue("Window should be scrolled down",
+                windowScrollBefore > 100);
+        Assert.assertTrue("Outer container should be scrolled down",
+                outerScrollBefore > 50);
+        Assert.assertTrue("Inner container (no ID) should be scrolled down",
+                innerScrollBefore > 50);
+
+        String attachIdBefore = getAttachId();
+
+        // Simulate hot-swap: directly trigger onReload on the dev-tools
+        // WebSocket connection. In a real hot-swap, the server pushes the
+        // reload message directly via WebSocket without a prior UIDL update.
+        executeScript(
+                "document.querySelector('vaadin-dev-tools').frontendConnection.onReload('full-refresh')");
+
+        // Wait for the UI to refresh
+        waitUntil(d -> !attachIdBefore.equals(getAttachId()), 10);
+
+        waitForScrollRestoration("window", windowScrollBefore);
+        waitForScrollRestoration("#outer-scroll", outerScrollBefore);
+        waitForScrollRestoration(INNER_SCROLL_SELECTOR, innerScrollBefore);
+    }
+
+    @Test
+    public void scrollPositionPreservedAfterFullPageReload() {
+        open();
+        waitForElementPresent(By.id("item-50"));
+
+        scrollAllContainers();
+
+        int windowScrollBefore = getScrollY();
+        int outerScrollBefore = getScrollTop("#outer-scroll");
+        int innerScrollBefore = getScrollTop(INNER_SCROLL_SELECTOR);
+
+        Assert.assertTrue("Window should be scrolled down",
+                windowScrollBefore > 100);
+        Assert.assertTrue("Outer container should be scrolled down",
+                outerScrollBefore > 50);
+        Assert.assertTrue("Inner container (no ID) should be scrolled down",
+                innerScrollBefore > 50);
+
+        // Simulate hot-swap full reload: saves scroll to sessionStorage
+        // and calls window.location.reload().
+        executeScript(
+                "document.querySelector('vaadin-dev-tools').frontendConnection.onReload('reload')");
+
+        // Wait for the page to reload and render
+        waitForElementPresent(By.id("item-50"));
+
+        waitForScrollRestoration("window", windowScrollBefore);
+        waitForScrollRestoration("#outer-scroll", outerScrollBefore);
+        waitForScrollRestoration(INNER_SCROLL_SELECTOR, innerScrollBefore);
+    }
+
+    private void scrollAllContainers() {
+        // Scroll the inner container (no ID, found by CSS selector)
+        executeScript("document.querySelector(arguments[0]).scrollTop = 300",
+                INNER_SCROLL_SELECTOR);
+        // Scroll the outer container
+        executeScript(
+                "document.querySelector('#outer-scroll').scrollTop = 400");
+        // Scroll the window
+        executeScript("document.getElementById('item-50').scrollIntoView()");
+        sleep(500);
+    }
+
+    private int getScrollTop(String cssSelector) {
+        return ((Number) executeScript(
+                "return document.querySelector(arguments[0]).scrollTop",
+                cssSelector)).intValue();
+    }
+
+    private void waitForScrollRestoration(String target, int expectedScrollY) {
+        if ("window".equals(target)) {
+            waitUntil(d -> Math.abs(getScrollY() - expectedScrollY) < 5, 10);
+        } else {
+            waitUntil(d -> Math.abs(getScrollTop(target) - expectedScrollY) < 5,
+                    10);
+        }
+    }
+
+    private void sleep(int millis) {
+        try {
+            Thread.sleep(millis);
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    }
+}

vaadin-dev-server/src/main/frontend/hotswap-scroll.ts

@@ -0,0 +1,132 @@
+export type ScrollSnapshot = Record<string, { scrollTop: number; scrollLeft: number }>;
+
+// Matches ROOT_NODE_ID in Flow.ts / StateTree.java
+const ROOT_NODE_ID = 1;
+const REFRESH_UI_EVENT = 'vaadin-refresh-ui';
+
+/**
+ * Builds a CSS selector path for an element. Uses the element's ID if present,
+ * otherwise walks up the DOM building nth-of-type selectors, stopping at the
+ * nearest ancestor with an ID.
+ */
+function getElementPath(el: Element): string {
+  if (el.id) return '#' + CSS.escape(el.id);
+  const parts: string[] = [];
+  let current: Element | null = el;
+  while (current && current !== document.documentElement && current !== document.body) {
+    if (current.id) {
+      parts.unshift('#' + CSS.escape(current.id));
+      break;
+    }
+    const parent = current.parentElement;
+    if (!parent) break;
+    let index = 1;
+    let sibling: Element | null = current.previousElementSibling;
+    while (sibling) {
+      if (sibling.tagName === current.tagName) index++;
+      sibling = sibling.previousElementSibling;
+    }
+    parts.unshift(current.tagName.toLowerCase() + ':nth-of-type(' + index + ')');
+    current = parent;
+  }
+  return parts.length > 0 ? parts.join(' > ') : '';
+}
+
+function getFlowClients(): any[] {
+  const anyVaadin = (window as any).Vaadin;
+  return Object.keys(anyVaadin?.Flow?.clients || {})
+    .filter((key) => key !== 'TypeScript')
+    .map((id) => anyVaadin.Flow.clients[id]);
+}
+
+/**
+ * Captures scroll positions of the window and all scrolled elements.
+ * Elements are keyed by CSS selector path so they can be found after DOM rebuild.
+ */
+export function captureScrollPositions(): ScrollSnapshot {
+  const snapshot: ScrollSnapshot = {};
+  if (window.scrollX !== 0 || window.scrollY !== 0) {
+    snapshot['__window__'] = { scrollTop: window.scrollY, scrollLeft: window.scrollX };
+  }
+  document.querySelectorAll('*').forEach((el) => {
+    if (el.scrollTop > 0 || el.scrollLeft > 0) {
+      const path = getElementPath(el);
+      if (path) {
+        snapshot[path] = { scrollTop: el.scrollTop, scrollLeft: el.scrollLeft };
+      }
+    }
+  });
+  return snapshot;
+}
+
+/**
+ * Captures scroll positions, sends a ui-refresh event to all Flow clients,
+ * and restores scroll positions once the clients are idle.
+ * Used by both the Push-based (vaadin-refresh-ui event) and WebSocket-based
+ * hot-swap paths.
+ */
+export function refreshWithScrollPreservation(fullRefresh: boolean): void {
+  const snapshot = captureScrollPositions();
+  getFlowClients().forEach((client: any) => {
+    if (client.sendEventMessage) {
+      client.sendEventMessage(ROOT_NODE_ID, 'ui-refresh', { fullRefresh });
+    }
+  });
+  restoreScrollPositions(snapshot);
+}
+
+let refreshUIHandlerRegistered = false;
+
+/**
+ * Registers a window event listener for 'vaadin-refresh-ui' that triggers
+ * a scroll-preserving UI refresh. Guards against double-registration.
+ */
+export function registerRefreshUIHandler(): void {
+  if (refreshUIHandlerRegistered) {
+    return;
+  }
+  refreshUIHandlerRegistered = true;
+  window.addEventListener(REFRESH_UI_EVENT, (ev: any) => {
+    refreshWithScrollPreservation(ev.detail?.fullRefresh === true);
+  });
+}
+
+/**
+ * Restores scroll positions after a hot-swap UI refresh completes.
+ * Polls Flow client isActive() to wait until UIDL processing is done,
+ * then uses requestAnimationFrame to restore all captured scroll positions.
+ */
+export function restoreScrollPositions(snapshot: ScrollSnapshot): void {
+  if (Object.keys(snapshot).length === 0) {
+    return;
+  }
+  const MAX_POLL_ATTEMPTS = 200; // 200 * 50ms = 10 seconds
+  let attempts = 0;
+
+  const applyScroll = () => {
+    requestAnimationFrame(() => {
+      for (const [key, pos] of Object.entries(snapshot)) {
+        if (key === '__window__') {
+          window.scrollTo(pos.scrollLeft, pos.scrollTop);
+        } else {
+          const el = document.querySelector(key);
+          if (el) {
+            el.scrollTop = pos.scrollTop;
+            el.scrollLeft = pos.scrollLeft;
+          }
+        }
+      }
+    });
+  };
+
+  const poll = () => {
+    const clients = getFlowClients();
+    const allIdle = clients.length > 0 && clients.every((c: any) => !c.isActive());
+    if (allIdle || ++attempts >= MAX_POLL_ATTEMPTS) {
+      applyScroll();
+    } else {
+      setTimeout(poll, 50);
+    }
+  };
+  setTimeout(poll, 50);
+}