feat: add UI router state signal (#24234)

Expose UI.routerStateSignal() as a read-only Signal<RouterState> holding
the current Location, RouteParameters, active chain and navigation
target class. The signal is updated atomically alongside
AfterNavigationEvent dispatch, so reactive consumers and listeners
observe the same state.

Lets components observe the active route via Signal.effect instead of
registering an AfterNavigationListener and manually fetching the initial
state from UIInternals on attach. Fine-grained projections (current
location, route parameters, leaf view) are derivable with Signal.map;
two-way URL/parameter binding is intentionally left for a follow-up so
its API can be designed independently.

Author: Artur-

flow-server/src/main/java/com/vaadin/flow/component/UI.java

@@ -71,6 +71,7 @@
 import com.vaadin.flow.router.RouteParameters;
 import com.vaadin.flow.router.Router;
 import com.vaadin.flow.router.RouterLayout;
+import com.vaadin.flow.router.RouterState;
 import com.vaadin.flow.router.internal.HasUrlParameterFormat;
 import com.vaadin.flow.router.internal.PathUtil;
 import com.vaadin.flow.server.Command;
@@ -842,6 +843,37 @@ public Signal<Locale> localeSignal() {
         return localeSignal.asReadonly();
     }
 
+    /**
+     * Gets a read-only signal that holds the current {@link RouterState} of
+     * this UI.
+     * <p>
+     * The signal value is updated whenever a navigation completes, immediately
+     * before {@link AfterNavigationListener}s are notified, so reactive
+     * consumers and listeners observe the same state. Use {@link Signal#get()}
+     * to read reactively (creates a dependency when called inside a
+     * {@link Signal#effect}). Use {@link Signal#peek()} for a non-reactive
+     * snapshot.
+     * <p>
+     * Before the first navigation completes, the value is a {@code
+     * RouterState} with an empty {@link Location}, empty
+     * {@link RouteParameters}, an empty active chain and a {@code null}
+     * navigation target.
+     * <p>
+     * Fine-grained projections can be derived with {@link Signal#map}, for
+     * example:
+     *
+     * <pre>
+     * Signal&lt;Location&gt; locationSignal = ui.routerStateSignal()
+     *         .map(RouterState::location);
+     * </pre>
+     *
+     * @return a read-only signal holding the current router state, never
+     *         {@code null}
+     */
+    public Signal<RouterState> routerStateSignal() {
+        return internals.getRouterStateSignal();
+    }
+
     /**
      * Sets the locale for this UI.
      * <p>

flow-server/src/main/java/com/vaadin/flow/component/internal/UIInternals.java

@@ -77,8 +77,10 @@
 import com.vaadin.flow.router.Location;
 import com.vaadin.flow.router.NavigationTrigger;
 import com.vaadin.flow.router.Route;
+import com.vaadin.flow.router.RouteParameters;
 import com.vaadin.flow.router.Router;
 import com.vaadin.flow.router.RouterLayout;
+import com.vaadin.flow.router.RouterState;
 import com.vaadin.flow.router.internal.AfterNavigationHandler;
 import com.vaadin.flow.router.internal.BeforeEnterHandler;
 import com.vaadin.flow.router.internal.BeforeLeaveHandler;
@@ -88,6 +90,7 @@
 import com.vaadin.flow.server.communication.PushConnection;
 import com.vaadin.flow.shared.Registration;
 import com.vaadin.flow.shared.communication.PushMode;
+import com.vaadin.flow.signals.Signal;
 import com.vaadin.flow.signals.local.ValueSignal;
 
 /**
@@ -200,6 +203,12 @@ public List<Object> getParameters() {
     private Location viewLocation = new Location("");
     private ArrayList<HasElement> routerTargetChain = new ArrayList<>();
 
+    private final ValueSignal<RouterState> routerStateSignal = new ValueSignal<>(
+            new RouterState(new Location(""), RouteParameters.empty(),
+                    Collections.emptyList(), null));
+    private final Signal<RouterState> readonlyRouterStateSignal = routerStateSignal
+            .asReadonly();
+
     private HashMap<Class<?>, List<?>> listeners = new HashMap<>();
 
     private Location lastHandledNavigation = null;
@@ -976,6 +985,30 @@ public Location getActiveViewLocation() {
         return viewLocation;
     }
 
+    /**
+     * Gets the cached read-only {@link Signal} that holds the current
+     * {@link RouterState} for this UI. Backs
+     * {@link com.vaadin.flow.component.UI#routerStateSignal()}.
+     *
+     * @return the read-only router state signal, not <code>null</code>
+     */
+    public Signal<RouterState> getRouterStateSignal() {
+        return readonlyRouterStateSignal;
+    }
+
+    /**
+     * Updates the {@link RouterState} value held by this UI's router state
+     * signal. Called by the navigation pipeline whenever a navigation
+     * completes, immediately before {@link AfterNavigationListener}s are
+     * notified.
+     *
+     * @param state
+     *            the new router state, not <code>null</code>
+     */
+    public void updateRouterState(RouterState state) {
+        routerStateSignal.set(state);
+    }
+
     /**
      * Gets the VaadinSession to which the related UI is attached.
      *

flow-server/src/main/java/com/vaadin/flow/router/RouterState.java

@@ -0,0 +1,75 @@
+/*
+ * 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.router;
+
+import java.io.Serializable;
+import java.util.List;
+import java.util.Objects;
+import java.util.Optional;
+
+import com.vaadin.flow.component.Component;
+import com.vaadin.flow.component.HasElement;
+
+/**
+ * An immutable snapshot of a UI's current navigation state.
+ * <p>
+ * Carried by {@link com.vaadin.flow.component.UI#routerStateSignal()} so that
+ * components can observe the active route reactively, instead of registering an
+ * {@link AfterNavigationListener} and manually fetching the initial state on
+ * attach.
+ * <p>
+ * The snapshot covers the same data already available through
+ * {@link AfterNavigationEvent} plus the navigation target class. It is produced
+ * at the same point that {@code AfterNavigationEvent} is dispatched, so the
+ * signal value and the listener notification are always consistent.
+ *
+ * @param location
+ *            the location of the current view (path, query parameters,
+ *            fragment); never {@code null}. Before the first navigation, this
+ *            is an empty location ({@code new Location("")}).
+ * @param routeParameters
+ *            route parameters extracted from the URL; never {@code null}. May
+ *            be {@link RouteParameters#empty()}.
+ * @param activeChain
+ *            unmodifiable list of the currently active route target and its
+ *            parent layouts, leaf first. Never {@code null}; empty before the
+ *            first navigation completes.
+ * @param navigationTarget
+ *            the class of the leaf route target. {@code null} before the first
+ *            navigation completes.
+ */
+public record RouterState(Location location, RouteParameters routeParameters,
+        List<HasElement> activeChain,
+        Class<? extends Component> navigationTarget) implements Serializable {
+
+    public RouterState {
+        Objects.requireNonNull(location, "location cannot be null");
+        Objects.requireNonNull(routeParameters,
+                "routeParameters cannot be null");
+        Objects.requireNonNull(activeChain, "activeChain cannot be null");
+        activeChain = List.copyOf(activeChain);
+    }
+
+    /**
+     * Returns the currently shown leaf view, if any.
+     *
+     * @return the leaf route target, or empty if no navigation has happened yet
+     */
+    public Optional<HasElement> currentView() {
+        return activeChain.isEmpty() ? Optional.empty()
+                : Optional.of(activeChain.get(0));
+    }
+}

flow-server/src/main/java/com/vaadin/flow/router/internal/AbstractNavigationStateRenderer.java

@@ -67,6 +67,7 @@
 import com.vaadin.flow.router.RouteParameters;
 import com.vaadin.flow.router.Router;
 import com.vaadin.flow.router.RouterLayout;
+import com.vaadin.flow.router.RouterState;
 import com.vaadin.flow.server.Constants;
 import com.vaadin.flow.server.HttpStatusCode;
 import com.vaadin.flow.server.RouteRegistry;
@@ -396,6 +397,12 @@ private Optional<Integer> handleBeforeNavigationEvents(
      */
     private void handleAfterNavigationEvents(UI ui,
             RouteParameters parameters) {
+        ui.getInternals()
+                .updateRouterState(new RouterState(
+                        locationChangeEvent.getLocation(), parameters,
+                        ui.getInternals().getActiveRouterTargetsChain(),
+                        navigationState.getNavigationTarget()));
+
         List<AfterNavigationHandler> afterNavigationHandlers = new ArrayList<>(
                 ui.getNavigationListeners(AfterNavigationHandler.class));
         afterNavigationHandlers

flow-server/src/test/java/com/vaadin/flow/component/UIRouterStateSignalTest.java

@@ -0,0 +1,96 @@
+/*
+ * 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.component;
+
+import java.util.Collections;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import com.vaadin.flow.dom.SignalsUnitTest;
+import com.vaadin.flow.router.Location;
+import com.vaadin.flow.router.RouteParameters;
+import com.vaadin.flow.router.RouterState;
+import com.vaadin.flow.signals.Signal;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+/**
+ * Unit tests for {@link UI#routerStateSignal()}.
+ */
+class UIRouterStateSignalTest extends SignalsUnitTest {
+
+    @Tag("test-view")
+    private static class TestView extends Component {
+    }
+
+    @Test
+    void routerStateSignal_returnsCachedReadonlyInstance() {
+        UI ui = UI.getCurrent();
+        Signal<RouterState> a = ui.routerStateSignal();
+        Signal<RouterState> b = ui.routerStateSignal();
+
+        assertNotNull(a, "routerStateSignal() should never return null");
+        assertSame(a, b,
+                "Repeated calls must return the same cached read-only signal");
+    }
+
+    @Test
+    void routerStateSignal_initialValueHasEmptyChain() {
+        UI ui = UI.getCurrent();
+        RouterState initial = ui.routerStateSignal().peek();
+
+        assertNotNull(initial);
+        assertEquals("", initial.location().getPath());
+        assertTrue(initial.activeChain().isEmpty());
+        assertTrue(initial.currentView().isEmpty());
+        assertTrue(initial.routeParameters().getParameterNames().isEmpty());
+    }
+
+    @Test
+    void routerStateSignal_updatedAfterUpdateRouterState() {
+        UI ui = UI.getCurrent();
+        Signal<RouterState> signal = ui.routerStateSignal();
+
+        TestView leaf = new TestView();
+        RouterState newState = new RouterState(new Location("foo/bar"),
+                RouteParameters.empty(), List.of(leaf), TestView.class);
+
+        ui.getInternals().updateRouterState(newState);
+
+        RouterState observed = signal.peek();
+        assertEquals("foo/bar", observed.location().getPath());
+        assertSame(leaf, observed.currentView().orElseThrow());
+        assertEquals(TestView.class, observed.navigationTarget());
+    }
+
+    @Test
+    void routerStateSignal_consecutiveUpdatesArePropagated() {
+        UI ui = UI.getCurrent();
+        Signal<RouterState> signal = ui.routerStateSignal();
+
+        ui.getInternals().updateRouterState(new RouterState(new Location("a"),
+                RouteParameters.empty(), Collections.emptyList(), null));
+        assertEquals("a", signal.peek().location().getPath());
+
+        ui.getInternals().updateRouterState(new RouterState(new Location("b"),
+                RouteParameters.empty(), Collections.emptyList(), null));
+        assertEquals("b", signal.peek().location().getPath());
+    }
+}