feat: ignore trailing slashes during route matching, configurable via trailingSlash prop (#226)

Author: uhyo

packages/docs/src/pages/ApiComponentsPage.tsx

@@ -66,6 +66,21 @@ export function ApiComponentsPage() {
                 <code>window.location</code> without navigation interception (MPA behavior).
               </td>
             </tr>
+            <tr>
+              <td>
+                <code>trailingSlash</code>
+              </td>
+              <td>
+                <code>{'"ignore" | "strict"'}</code>
+              </td>
+              <td>
+                How trailing slashes are treated during route matching. <code>"ignore"</code>{" "}
+                (default) ignores a single trailing slash on the pathname or on route{" "}
+                <code>path</code> patterns, so <code>/users/</code> matches{" "}
+                <code>path: "/users"</code>; the URL itself is never rewritten.{" "}
+                <code>"strict"</code> requires pathnames to match patterns exactly.
+              </td>
+            </tr>
             <tr>
               <td>
                 <code>ssr</code>

packages/docs/src/pages/LearnNestedRoutesPage.tsx

@@ -244,6 +244,24 @@ const routes = [
 
 // /files → matches FileExplorer (outlet is null)
 // /files/123 → matches FileExplorer + FileDetails`}</CodeBlock>
+
+        <h4>Trailing Slashes</h4>
+        <p>
+          By default, a single trailing slash in the URL is <strong>ignored</strong> during
+          matching: <code>/users/</code> matches a route with <code>path: "/users"</code> (and a
+          trailing slash in a route's <code>path</code> is likewise ignored). Only matching is
+          affected&mdash;the URL itself is never rewritten, so <code>useLocation()</code> still
+          reports the pathname with its trailing slash. The root path <code>/</code> is unaffected.
+        </p>
+        <p>
+          To require URLs to match patterns exactly, set <code>trailingSlash: "strict"</code> on the{" "}
+          <code>{"<Router>"}</code>:
+        </p>
+        <CodeBlock language="tsx">{`<Router routes={routes} trailingSlash="strict" />
+
+// With trailingSlash="strict":
+// /users  → matches path: "/users"
+// /users/ → does NOT match path: "/users"`}</CodeBlock>
       </section>
 
       <section>
@@ -564,6 +582,10 @@ function App() {
           </li>
           <li>Child route paths are relative to their parent route's path</li>
           <li>Parent routes use prefix matching; leaf routes use exact matching</li>
+          <li>
+            A single trailing slash is ignored during matching by default; opt into strict matching
+            with <code>trailingSlash: "strict"</code> on <code>{"<Router>"}</code>
+          </li>
           <li>Use pathless routes for layouts that don't affect the URL</li>
           <li>Parent route loaders run before children, making them ideal for shared data</li>
           <li>Deep nesting is supported&mdash;compose as many layout levels as you need</li>

packages/router/src/Router/index.tsx

@@ -17,6 +17,7 @@ import {
   type NavigateOptions,
   type OnNavigateCallback,
   type FallbackMode,
+  type TrailingSlashMode,
   type TransitionTypeContext,
   internalRoutes,
 } from "../types.js";
@@ -95,6 +96,19 @@ export type RouterProps = {
    * ```
    */
   ssr?: SSRConfig;
+  /**
+   * How trailing slashes in the URL pathname are treated during route matching.
+   *
+   * - `"ignore"` (default): a single trailing slash is ignored, so `/users/`
+   *   matches a route with `path: "users"` (and a trailing slash in a route's
+   *   `path` pattern is likewise ignored). The URL itself is never rewritten —
+   *   only matching is affected, and the root pathname `/` is unaffected.
+   * - `"strict"`: pathnames must match patterns exactly; `/users/` does not
+   *   match `path: "users"`.
+   *
+   * @default "ignore"
+   */
+  trailingSlash?: TrailingSlashMode;
   /**
    * **Experimental.** Function returning the React transition types to attach
    * to entry-change transitions via `addTransitionType`. Called inside
@@ -118,6 +132,7 @@ export function Router({
   onNavigate,
   fallback = "none",
   ssr,
+  trailingSlash,
   experimentalTransitionTypes,
 }: RouterProps): ReactNode {
   const routes = internalRoutes(inputRoutes);
@@ -225,13 +240,22 @@ export function Router({
     });
   }, [adapter, startTransition]);
 
-  // Wrap in useEffectEvent so interception doesn't re-setup when routes or onNavigate change
+  // Wrap in useEffectEvent so interception doesn't re-setup when routes,
+  // onNavigate, or trailingSlash change
   const getRoutes = useEffectEvent(() => routes);
   const handleNavigate = useEffectEvent<OnNavigateCallback>((...args) => onNavigate?.(...args));
+  // Interception must match with the same trailing-slash policy as rendering,
+  // so the interception decision agrees with what will render.
+  const getMatchOptions = useEffectEvent(() => ({ trailingSlash }));
 
   // Set up navigation interception via adapter
   useEffect(() => {
-    return adapter.setupInterception(getRoutes, handleNavigate, blockerRegistry.checkAll);
+    return adapter.setupInterception(
+      getRoutes,
+      handleNavigate,
+      blockerRegistry.checkAll,
+      getMatchOptions,
+    );
   }, [adapter, blockerRegistry]);
 
   // Navigate function that returns a Promise
@@ -303,6 +327,7 @@ export function Router({
       // Routes with loaders are skipped (skipLoaders: true).
       const matched = matchRoutes(routes, urlObject?.pathname ?? null, {
         skipLoaders: true,
+        trailingSlash,
       });
       if (!matched) return null;
       return matched.map((m) => ({ ...m, data: undefined }));
@@ -314,7 +339,7 @@ export function Router({
 
     // Unified path: SSR with loaders or client-side.
     // Both cases match routes normally and execute loaders.
-    const matched = matchRoutes(routes, urlObject.pathname);
+    const matched = matchRoutes(routes, urlObject.pathname, { trailingSlash });
     if (!matched) return null;
 
     const entryKey = locationKey;
@@ -330,7 +355,16 @@ export function Router({
       // instance instead of the shared module-level cache.
       realLocationKey === null ? instanceLoaderCache : undefined,
     );
-  }, [routes, adapter, urlObject, runLoaders, locationKey, realLocationKey, instanceLoaderCache]);
+  }, [
+    routes,
+    adapter,
+    urlObject,
+    runLoaders,
+    trailingSlash,
+    locationKey,
+    realLocationKey,
+    instanceLoaderCache,
+  ]);
 
   const locationState = locationEntry?.state;
   const locationInfo = locationEntry?.info;

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

@@ -401,4 +401,80 @@ describe("Router", () => {
       expect(addTransitionTypeSpy).not.toHaveBeenCalled();
     });
   });
+
+  describe("trailingSlash prop", () => {
+    it("ignores a trailing slash by default", () => {
+      mockNavigation = setupNavigationMock("http://localhost/about/");
+
+      const routes: RouteDefinition[] = [{ path: "/about", component: () => <div>About</div> }];
+
+      render(<Router routes={routes} />);
+      expect(screen.getByText("About")).toBeInTheDocument();
+    });
+
+    it("does not rewrite the URL when ignoring a trailing slash", () => {
+      mockNavigation = setupNavigationMock("http://localhost/about/");
+
+      function About() {
+        const location = useLocation();
+        return <div data-testid="pathname">{location.pathname}</div>;
+      }
+
+      const routes: RouteDefinition[] = [{ path: "/about", component: About }];
+
+      render(<Router routes={routes} />);
+      expect(screen.getByTestId("pathname").textContent).toBe("/about/");
+    });
+
+    it("renders nothing for a trailing-slash URL in strict mode", () => {
+      mockNavigation = setupNavigationMock("http://localhost/about/");
+
+      const routes: RouteDefinition[] = [{ path: "/about", component: () => <div>About</div> }];
+
+      const { container } = render(<Router routes={routes} trailingSlash="strict" />);
+      expect(container.textContent).toBe("");
+    });
+
+    it("intercepts navigation to a trailing-slash URL by default", () => {
+      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).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ intercepting: true }),
+      );
+      expect(screen.getByText("About")).toBeInTheDocument();
+    });
+
+    it("does not intercept navigation to a trailing-slash URL in strict mode", () => {
+      const onNavigate = vi.fn();
+
+      const routes: RouteDefinition[] = [
+        { path: "/", component: () => <div>Home</div> },
+        { path: "/about", component: () => <div>About</div> },
+      ];
+
+      render(<Router routes={routes} onNavigate={onNavigate} trailingSlash="strict" />);
+
+      act(() => {
+        mockNavigation.__simulateNavigationWithEvent("http://localhost/about/");
+      });
+
+      expect(onNavigate).toHaveBeenCalledWith(
+        expect.anything(),
+        expect.objectContaining({ matches: null, intercepting: false }),
+      );
+    });
+  });
 });

packages/router/src/__tests__/matchRoutes.test.ts

@@ -981,4 +981,101 @@ describe("matchRoutes", () => {
       expect(result).toBeNull();
     });
   });
+
+  describe("trailing slash handling", () => {
+    describe('default mode ("ignore")', () => {
+      it("matches a pathname with trailing slash against an exact route", () => {
+        const routes = internalRoutes([{ path: "/users", component: () => null }]);
+
+        const result = matchRoutes(routes, "/users/");
+        expect(result).toHaveLength(1);
+        expect(result![0].pathname).toBe("/users");
+      });
+
+      it("matches a pathname with trailing slash against a param route", () => {
+        const routes = internalRoutes([{ path: "/users/:id", component: () => null }]);
+
+        const result = matchRoutes(routes, "/users/123/");
+        expect(result).toHaveLength(1);
+        expect(result![0].params).toEqual({ id: "123" });
+        expect(result![0].pathname).toBe("/users/123");
+      });
+
+      it("matches a pathname with trailing slash against nested routes", () => {
+        const routes = internalRoutes([
+          {
+            path: "/users",
+            component: () => null,
+            children: [{ path: ":id", component: () => null }],
+          },
+        ]);
+
+        const result = matchRoutes(routes, "/users/123/");
+        expect(result).toHaveLength(2);
+        expect(result![1].params).toEqual({ id: "123" });
+      });
+
+      it("ignores a trailing slash in the route pattern", () => {
+        const routes = internalRoutes([{ path: "/users/", component: () => null }]);
+
+        expect(matchRoutes(routes, "/users")).toHaveLength(1);
+        expect(matchRoutes(routes, "/users/")).toHaveLength(1);
+      });
+
+      it("does not strip the root pathname", () => {
+        const routes = internalRoutes([{ path: "/", component: () => null }]);
+
+        const result = matchRoutes(routes, "/");
+        expect(result).toHaveLength(1);
+      });
+
+      it("excludes the trailing slash from wildcard-like captures", () => {
+        const routes = internalRoutes([{ path: "/files/:path+", component: () => null }]);
+
+        const result = matchRoutes(routes, "/files/a/b/");
+        expect(result).toHaveLength(1);
+        expect(result![0].params).toEqual({ path: "a/b" });
+      });
+
+      it("strips only a single trailing slash", () => {
+        const routes = internalRoutes([{ path: "/users", component: () => null }]);
+
+        // "/users//" contains an empty segment and is not repaired
+        expect(matchRoutes(routes, "/users//")).toBeNull();
+      });
+
+      it("does not fall through to a catch-all for a trailing-slash URL", () => {
+        const routes = internalRoutes([
+          { path: "/users", component: () => null },
+          { path: "/:rest*", component: () => null },
+        ]);
+
+        const result = matchRoutes(routes, "/users/");
+        expect(result).toHaveLength(1);
+        expect(result![0].route.path).toBe("/users");
+      });
+    });
+
+    describe('"strict" mode', () => {
+      it("does not match a pathname with trailing slash against an exact route", () => {
+        const routes = internalRoutes([{ path: "/users", component: () => null }]);
+
+        expect(matchRoutes(routes, "/users/", { trailingSlash: "strict" })).toBeNull();
+        expect(matchRoutes(routes, "/users", { trailingSlash: "strict" })).toHaveLength(1);
+      });
+
+      it("keeps a trailing slash in the route pattern significant", () => {
+        const routes = internalRoutes([{ path: "/users/", component: () => null }]);
+
+        expect(matchRoutes(routes, "/users", { trailingSlash: "strict" })).toBeNull();
+        expect(matchRoutes(routes, "/users/", { trailingSlash: "strict" })).toHaveLength(1);
+      });
+
+      it("still matches the root pathname", () => {
+        const routes = internalRoutes([{ path: "/", component: () => null }]);
+
+        expect(matchRoutes(routes, "/", { trailingSlash: "strict" })).toHaveLength(1);
+      });
+    });
+  });
 });

packages/router/src/core/NavigationAPIAdapter.ts

@@ -6,7 +6,7 @@ import type {
   NavigationType,
   OnNavigateCallback,
 } from "../types.js";
-import { matchRoutes } from "./matchRoutes.js";
+import { matchRoutes, type MatchRoutesOptions } from "./matchRoutes.js";
 import { isBypassInterception } from "../bypassInterception.js";
 import {
   executeLoaders,
@@ -260,6 +260,7 @@ export class NavigationAPIAdapter implements RouterAdapter {
     getRoutes: () => InternalRouteDefinition[],
     onNavigate?: OnNavigateCallback,
     checkBlockers?: () => boolean,
+    getMatchOptions?: () => MatchRoutesOptions,
   ): (() => void) | undefined {
     const handleNavigate = (event: NavigateEvent) => {
       // If the navigation was triggered by hardReload/hardNavigate, skip blockers and interception
@@ -305,7 +306,7 @@ export class NavigationAPIAdapter implements RouterAdapter {
 
       // Check if the URL matches any of our routes
       const url = new URL(event.destination.url);
-      const matched = matchRoutes(getRoutes(), url.pathname);
+      const matched = matchRoutes(getRoutes(), url.pathname, getMatchOptions?.());
 
       const isFormSubmission = event.formData !== null;
 

packages/router/src/core/RouterAdapter.ts

@@ -4,6 +4,7 @@ import type {
   NavigationType,
   OnNavigateCallback,
 } from "../types.js";
+import type { MatchRoutesOptions } from "./matchRoutes.js";
 
 /**
  * The type of change that caused a location entry update.
@@ -85,11 +86,16 @@ export interface RouterAdapter {
    * @param onNavigate - Optional callback invoked before navigation is intercepted
    * @param checkBlockers - Optional function to check if any blockers are active.
    *                        If this function returns true, navigation is prevented.
+   * @param getMatchOptions - Optional function that returns the matching options
+   *                          (e.g. trailing slash handling). Must be consistent with
+   *                          the options the Router uses for rendering, so the
+   *                          interception decision agrees with what will render.
    */
   setupInterception(
     getRoutes: () => InternalRouteDefinition[],
     onNavigate?: OnNavigateCallback,
     checkBlockers?: () => boolean,
+    getMatchOptions?: () => MatchRoutesOptions,
   ): (() => void) | undefined;
 
   /**