feat: expose entryId and entryKey from Navigation API in useLocation

packages/docs/src/pages/ApiHooksPage.tsx

@@ -21,7 +21,16 @@ function MyComponent() {
   console.log(location.pathname);  // "/users/123"
   console.log(location.search);    // "?tab=profile"
   console.log(location.hash);      // "#section"
+  console.log(location.entryId);   // NavigationHistoryEntry.id or null
+  console.log(location.entryKey);  // NavigationHistoryEntry.key or null
 }`}</CodeBlock>
+        <p>
+          <code>entryId</code> and <code>entryKey</code> are <code>null</code>{" "}
+          when the Navigation API is unavailable. Do not render them directly in
+          DOM — they are not available during SSR and will cause a hydration
+          mismatch. Use them as a React <code>key</code> or in effects/callbacks
+          instead.
+        </p>
       </article>
 
       <article className="api-item">

packages/docs/src/pages/ApiTypesPage.tsx

@@ -335,7 +335,24 @@ routeState<{ tab: string }>()({
   pathname: string;
   search: string;
   hash: string;
+  entryId: string | null;   // NavigationHistoryEntry.id
+  entryKey: string | null;  // NavigationHistoryEntry.key
 }`}</CodeBlock>
+        <p>
+          <code>entryId</code> and <code>entryKey</code> expose the
+          corresponding properties from the Navigation API's{" "}
+          <code>NavigationHistoryEntry</code>. <code>entryId</code> is a unique
+          identifier for the entry — a new id is assigned when the entry is
+          replaced. <code>entryKey</code> represents the slot in the entry list
+          and is stable across replacements. Both are <code>null</code> when the
+          Navigation API is unavailable (e.g., in static fallback mode).
+        </p>
+        <p>
+          <strong>Warning:</strong> Do not render these values directly in DOM,
+          as they are not available during SSR and will cause a hydration
+          mismatch. They are best suited for use as a React <code>key</code> or
+          in effects/callbacks.
+        </p>
       </article>
 
       <article className="api-item">

packages/router/src/Router/index.tsx

@@ -263,11 +263,25 @@ export function Router({
 
   const locationState = locationEntry?.state;
   const locationInfo = locationEntry?.info;
+  const entryId =
+    locationEntry?.entryId ??
+    (isServerSnapshot(locationEntryInternal)
+      ? locationEntryInternal.actualLocationEntry?.entryId
+      : null) ??
+    null;
+  const entryKey =
+    locationEntry?.entryKey ??
+    (isServerSnapshot(locationEntryInternal)
+      ? locationEntryInternal.actualLocationEntry?.entryKey
+      : null) ??
+    null;
   const routerContextValue: RouterContextValue = useMemo(
     () => ({
       locationState,
       locationInfo,
       url: urlObject,
+      entryId,
+      entryKey,
       isPending,
       navigateAsync,
       updateCurrentEntryState,
@@ -276,6 +290,8 @@ export function Router({
       locationState,
       locationInfo,
       urlObject,
+      entryId,
+      entryKey,
       isPending,
       navigateAsync,
       updateCurrentEntryState,

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

@@ -143,6 +143,26 @@ describe("Fallback Mode", () => {
       expect(screen.getByTestId("hash").textContent).toBe("#section");
     });
 
+    it("returns null for entryId and entryKey when Navigation API is unavailable", () => {
+      setupStaticLocation("http://localhost/");
+
+      function Page() {
+        const location = useLocation();
+        return (
+          <div>
+            <span data-testid="entryId">{location.entryId ?? "null"}</span>
+            <span data-testid="entryKey">{location.entryKey ?? "null"}</span>
+          </div>
+        );
+      }
+
+      const routes: RouteDefinition[] = [{ path: "/", component: Page }];
+
+      render(<Router routes={routes} fallback="static" />);
+      expect(screen.getByTestId("entryId").textContent).toBe("null");
+      expect(screen.getByTestId("entryKey").textContent).toBe("null");
+    });
+
     it("renders nothing when no route matches", () => {
       setupStaticLocation("http://localhost/unknown");
 
@@ -431,6 +451,24 @@ describe("ssr", () => {
     expect(screen.getByTestId("hash").textContent).toBe("");
   });
 
+  it("returns null for entryId and entryKey during SSR", () => {
+    function Page() {
+      const location = useLocation();
+      return (
+        <div>
+          <span data-testid="entryId">{location.entryId ?? "null"}</span>
+          <span data-testid="entryKey">{location.entryKey ?? "null"}</span>
+        </div>
+      );
+    }
+
+    const routes: RouteDefinition[] = [{ path: "/about", component: Page }];
+
+    render(<Router routes={routes} ssr={{ path: "/about" }} />);
+    expect(screen.getByTestId("entryId").textContent).toBe("null");
+    expect(screen.getByTestId("entryKey").textContent).toBe("null");
+  });
+
   it("pathless route wrapping path-based children works with ssr.path", () => {
     const routes: RouteDefinition[] = [
       {

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

@@ -47,6 +47,28 @@ describe("hooks", () => {
       expect(screen.getByTestId("hash").textContent).toBe("#section");
     });
 
+    it("returns entryId and entryKey from Navigation API", () => {
+      function TestComponent() {
+        const location = useLocation();
+        return (
+          <div>
+            <span data-testid="entryId">{location.entryId ?? "null"}</span>
+            <span data-testid="entryKey">{location.entryKey ?? "null"}</span>
+          </div>
+        );
+      }
+
+      const routes: RouteDefinition[] = [
+        { path: "/", component: TestComponent },
+      ];
+
+      render(<Router routes={routes} />);
+
+      // The mock navigation generates UUIDs for id and key
+      expect(screen.getByTestId("entryId").textContent).not.toBe("null");
+      expect(screen.getByTestId("entryKey").textContent).not.toBe("null");
+    });
+
     it("throws when used outside Router", () => {
       function TestComponent() {
         useLocation();

packages/router/src/context/RouterContext.ts

@@ -14,6 +14,10 @@ export type RouterContextValue = {
   locationInfo: unknown;
   /** Current URL (null during SSR) */
   url: URL | null;
+  /** NavigationHistoryEntry.id — unique identifier for this entry. A new id is assigned when the entry is replaced. Null during SSR or when Navigation API is unavailable. */
+  entryId: string | null;
+  /** NavigationHistoryEntry.key — represents the slot in the entry list. Stable across replacements. Null during SSR or when Navigation API is unavailable. */
+  entryKey: string | null;
   /** Whether a navigation transition is pending */
   isPending: boolean;
   /** Navigate to a new URL and wait for completion */

packages/router/src/core/NavigationAPIAdapter.ts

@@ -64,6 +64,8 @@ export class NavigationAPIAdapter implements RouterAdapter {
     this.#cachedSnapshot = {
       url: new URL(entry.url),
       key: this.#effectiveKey(entry.id),
+      entryId: entry.id,
+      entryKey: entry.key,
       state: entry.getState(),
       info: this.#currentNavigationInfo,
     };

packages/router/src/core/RouterAdapter.ts

@@ -20,6 +20,10 @@ export type LocationEntry = {
   url: URL;
   /** Unique key for this entry (used for loader caching) */
   key: string;
+  /** NavigationHistoryEntry.id — unique identifier for this entry. A new id is assigned when the entry is replaced. */
+  entryId: string | null;
+  /** NavigationHistoryEntry.key — represents the slot in the entry list. Stable across replacements. */
+  entryKey: string | null;
   /** State associated with this entry */
   state: unknown;
   /** Ephemeral info from current navigation (undefined if not from navigation event) */

packages/router/src/core/StaticAdapter.ts

@@ -28,6 +28,8 @@ export class StaticAdapter implements RouterAdapter {
       this.#cachedSnapshot = {
         url: new URL(window.location.href),
         key: "__static__",
+        entryId: null,
+        entryKey: null,
         state: undefined,
         info: undefined,
       };

packages/router/src/hooks/useLocation.ts

@@ -12,7 +12,7 @@ export function useLocation(): Location {
     throw new Error("useLocation must be used within a Router");
   }
 
-  const { url } = context;
+  const { url, entryId, entryKey } = context;
 
   if (url === null) {
     throw new Error("useLocation: URL is not available during SSR.");
@@ -23,6 +23,8 @@ export function useLocation(): Location {
       pathname: url.pathname,
       search: url.search,
       hash: url.hash,
+      entryId,
+      entryKey,
     };
-  }, [url]);
+  }, [url, entryId, entryKey]);
 }

packages/router/src/types.ts

@@ -123,6 +123,26 @@ export type Location = {
   pathname: string;
   search: string;
   hash: string;
+  /**
+   * NavigationHistoryEntry.id — unique identifier for this entry.
+   * A new id is assigned when the entry is replaced.
+   * Null when Navigation API is unavailable.
+   *
+   * **Warning:** Do not render this value directly in DOM, as it is not
+   * available during SSR and will cause a hydration mismatch. Use it as a
+   * React `key` or in effects/callbacks instead.
+   */
+  entryId: string | null;
+  /**
+   * NavigationHistoryEntry.key — represents the slot in the entry list.
+   * Stable across replacements.
+   * Null when Navigation API is unavailable.
+   *
+   * **Warning:** Do not render this value directly in DOM, as it is not
+   * available during SSR and will cause a hydration mismatch. Use it as a
+   * React `key` or in effects/callbacks instead.
+   */
+  entryKey: string | null;
 };
 
 /**