feat: add onNavigate prop

Author: uhyo

packages/router/src/Router.tsx

@@ -10,6 +10,7 @@ import { RouteContext } from "./context/RouteContext.js";
 import {
   type NavigateOptions,
   type MatchedRouteWithData,
+  type OnNavigateCallback,
   internalRoutes,
 } from "./types.js";
 import { matchRoutes } from "./core/matchRoutes.js";
@@ -26,9 +27,20 @@ import type { RouteDefinition } from "./route.js";
 
 export type RouterProps = {
   routes: RouteDefinition[];
+  /**
+   * Callback invoked before navigation is intercepted.
+   * Call `event.preventDefault()` to prevent the router from handling this navigation.
+   *
+   * @param event - The NavigateEvent from the Navigation API
+   * @param matched - Array of matched routes, or null if no routes matched
+   */
+  onNavigate?: OnNavigateCallback;
 };
 
-export function Router({ routes: inputRoutes }: RouterProps): ReactNode {
+export function Router({
+  routes: inputRoutes,
+  onNavigate,
+}: RouterProps): ReactNode {
   const routes = internalRoutes(inputRoutes);
 
   const currentEntry = useSyncExternalStore(
@@ -39,8 +51,8 @@ export function Router({ routes: inputRoutes }: RouterProps): ReactNode {
 
   // Set up navigation interception
   useEffect(() => {
-    return setupNavigationInterception(routes);
-  }, [routes]);
+    return setupNavigationInterception(routes, onNavigate);
+  }, [routes, onNavigate]);
 
   // Navigate function for programmatic navigation
   const navigate = useCallback(

packages/router/src/__tests__/Router.test.tsx

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import { render, screen, act } from "@testing-library/react";
 import { Router } from "../Router.js";
 import { Outlet } from "../Outlet.js";
@@ -136,4 +136,110 @@ describe("Router", () => {
 
     expect(screen.getByText("About")).toBeInTheDocument();
   });
+
+  describe("onNavigate callback", () => {
+    it("calls onNavigate with NavigateEvent and matched routes before navigation", () => {
+      const onNavigate = vi.fn();
+
+      const routes: RouteDefinition[] = [
+        { path: "/", component: () => <div>Home</div> },
+        { path: "/about", component: () => <div>About</div> },
+      ];
+
+      render(<Router routes={routes} onNavigate={onNavigate} />);
+
+      act(() => {
+        const { proceed } = mockNavigation.__simulateNavigationWithEvent(
+          "http://localhost/about",
+        );
+        proceed();
+      });
+
+      expect(onNavigate).toHaveBeenCalledTimes(1);
+      expect(onNavigate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          destination: expect.objectContaining({
+            url: "http://localhost/about",
+          }),
+        }),
+        expect.arrayContaining([
+          expect.objectContaining({
+            pathname: "/about",
+          }),
+        ]),
+      );
+    });
+
+    it("prevents navigation when onNavigate calls event.preventDefault()", () => {
+      const onNavigate = vi.fn((event: NavigateEvent) => {
+        event.preventDefault();
+      });
+
+      const routes: RouteDefinition[] = [
+        { path: "/", component: () => <div>Home</div> },
+        { path: "/about", component: () => <div>About</div> },
+      ];
+
+      render(<Router routes={routes} onNavigate={onNavigate} />);
+
+      act(() => {
+        const { proceed } = mockNavigation.__simulateNavigationWithEvent(
+          "http://localhost/about",
+        );
+        proceed();
+      });
+
+      // Should still show Home because navigation was prevented
+      expect(screen.getByText("Home")).toBeInTheDocument();
+      expect(screen.queryByText("About")).not.toBeInTheDocument();
+    });
+
+    it("allows navigation when onNavigate does not call preventDefault()", () => {
+      const onNavigate = vi.fn(); // Does not call preventDefault
+
+      const routes: RouteDefinition[] = [
+        { path: "/", component: () => <div>Home</div> },
+        { path: "/about", component: () => <div>About</div> },
+      ];
+
+      render(<Router routes={routes} onNavigate={onNavigate} />);
+
+      act(() => {
+        const { proceed } = mockNavigation.__simulateNavigationWithEvent(
+          "http://localhost/about",
+        );
+        proceed();
+      });
+
+      expect(screen.getByText("About")).toBeInTheDocument();
+    });
+
+    it("calls onNavigate with null for unmatched routes", () => {
+      const onNavigate = vi.fn();
+
+      const routes: RouteDefinition[] = [
+        { path: "/", component: () => <div>Home</div> },
+      ];
+
+      render(<Router routes={routes} onNavigate={onNavigate} />);
+
+      act(() => {
+        const { proceed } = mockNavigation.__simulateNavigationWithEvent(
+          "http://localhost/unknown",
+        );
+        proceed();
+      });
+
+      // onNavigate should be called with null for unmatched routes
+      expect(onNavigate).toHaveBeenCalledTimes(1);
+      expect(onNavigate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          destination: expect.objectContaining({
+            url: "http://localhost/unknown",
+          }),
+        }),
+        null,
+      );
+    });
+  });
 });

packages/router/src/__tests__/setup.ts

@@ -38,6 +38,41 @@ export function createMockNavigation(initialUrl = "http://localhost/") {
     }
   };
 
+  // Create a mock NavigateEvent
+  const createMockNavigateEvent = (
+    destinationUrl: string,
+  ): NavigateEvent & { defaultPrevented: boolean } => {
+    let defaultPrevented = false;
+    return {
+      type: "navigate",
+      canIntercept: true,
+      hashChange: false,
+      destination: {
+        url: destinationUrl,
+        key: `key-${entries.length}`,
+        id: `id-${entries.length}`,
+        index: entries.length,
+        sameDocument: true,
+        getState: () => undefined,
+      },
+      navigationType: "push",
+      userInitiated: false,
+      signal: new AbortController().signal,
+      formData: null,
+      downloadRequest: null,
+      info: undefined,
+      hasUAVisualTransition: false,
+      intercept: vi.fn(),
+      scroll: vi.fn(),
+      get defaultPrevented() {
+        return defaultPrevented;
+      },
+      preventDefault: vi.fn(() => {
+        defaultPrevented = true;
+      }),
+    } as unknown as NavigateEvent & { defaultPrevented: boolean };
+  };
+
   const mockNavigation = {
     currentEntry,
     entries: () => [...entries],
@@ -88,11 +123,45 @@ export function createMockNavigation(initialUrl = "http://localhost/") {
       },
     ),
 
-    // Test helper to simulate navigation
+    // Test helper to simulate navigation (bypasses navigate event)
     __simulateNavigation(url: string, state?: unknown) {
       mockNavigation.navigate(url, { state });
     },
 
+    // Test helper to simulate navigation with navigate event dispatch
+    // This allows testing of onNavigate callback behavior
+    __simulateNavigationWithEvent(url: string): {
+      event: NavigateEvent & { defaultPrevented: boolean };
+      proceed: () => void;
+    } {
+      const newUrl = new URL(url, currentEntry.url).href;
+      const event = createMockNavigateEvent(newUrl);
+
+      // Dispatch navigate event first (allows onNavigate to be called)
+      dispatchEvent("navigate", event);
+
+      // Return event and a proceed function
+      // If event.defaultPrevented is true, proceeding should be skipped
+      return {
+        event,
+        proceed: () => {
+          if (!event.defaultPrevented) {
+            const newEntry = new MockNavigationHistoryEntry(
+              newUrl,
+              entries.length,
+            );
+            entries.push(newEntry);
+            currentEntry = newEntry;
+            mockNavigation.currentEntry = currentEntry;
+            dispatchEvent(
+              "currententrychange",
+              new Event("currententrychange"),
+            );
+          }
+        },
+      };
+    },
+
     // Test helper to simulate traverse navigation (back/forward)
     // This reuses an existing entry instead of creating a new one
     __simulateTraversal(entryIndex: number) {

packages/router/src/core/navigation.ts

@@ -1,4 +1,8 @@
-import type { InternalRouteDefinition, NavigateOptions } from "../types.js";
+import type {
+  InternalRouteDefinition,
+  NavigateOptions,
+  OnNavigateCallback,
+} from "../types.js";
 import { matchRoutes } from "./matchRoutes.js";
 import { executeLoaders, createLoaderRequest } from "./loaderCache.js";
 
@@ -72,6 +76,7 @@ export function getServerSnapshot(): null {
  */
 export function setupNavigationInterception(
   routes: InternalRouteDefinition[],
+  onNavigate?: OnNavigateCallback,
 ): () => void {
   if (!hasNavigation()) {
     return () => {};
@@ -87,6 +92,14 @@ export function setupNavigationInterception(
     const url = new URL(event.destination.url);
     const matched = matchRoutes(routes, url.pathname);
 
+    // Call onNavigate callback if provided (regardless of route match)
+    if (onNavigate) {
+      onNavigate(event, matched);
+      if (event.defaultPrevented) {
+        return; // Do not intercept, allow browser default
+      }
+    }
+
     if (matched) {
       // Abort initial load's loaders if this is the first navigation
       if (idleController) {

packages/router/src/index.ts

@@ -19,6 +19,7 @@ export type {
   MatchedRouteWithData,
   NavigateOptions,
   Location,
+  OnNavigateCallback,
 } from "./types.js";
 
 export type { LoaderArgs, RouteDefinition } from "./route.js";

packages/router/src/types.ts

@@ -74,3 +74,15 @@ export type Location = {
   search: string;
   hash: string;
 };
+
+/**
+ * Callback invoked before navigation is intercepted.
+ * Call `event.preventDefault()` to prevent the router from handling this navigation.
+ *
+ * @param event - The NavigateEvent from the Navigation API
+ * @param matched - Array of matched routes, or null if no routes matched
+ */
+export type OnNavigateCallback = (
+  event: NavigateEvent,
+  matched: readonly MatchedRoute[] | null,
+) => void;