add example

Author: gkurt

docs/router/guide/navigation.md

@@ -133,7 +133,7 @@ export type LinkOptions<
   preloadDelay?: number
   // If true, will render the link without the href attribute
   disabled?: boolean
-  // If true, clicking goes back via `history.back()` when the resolved target is the previous history entry (see "Direction-aware links" below)
+  // If true, clicking goes back via `history.back()` when the resolved target is the previous history entry (see "History-aware links" below)
   preferBack?: boolean
 }
 ```

examples/react/basic/src/main.tsx

@@ -123,6 +123,14 @@ function PostComponent() {
       <h4 className="text-xl font-bold">{post.title}</h4>
       <hr className="opacity-20" />
       <div className="text-sm">{post.body}</div>
+
+      <Link
+        to="/posts"
+        preferBack
+        className="py-1 px-2 rounded bg-green-600 text-white hover:opacity-90"
+      >
+        ← Back to posts
+      </Link>
     </div>
   )
 }

examples/react/basic/src/posts.ts

@@ -13,7 +13,7 @@ export const fetchPosts = async () => {
   await new Promise((r) => setTimeout(r, 500))
   return axios
     .get<Array<PostType>>('https://jsonplaceholder.typicode.com/posts')
-    .then((r) => r.data.slice(0, 10))
+    .then((r) => r.data.slice(0, 50))
 }
 
 export const fetchPost = async (postId: string) => {

packages/react-router/src/link.tsx

@@ -414,10 +414,8 @@ export function useLinkProps<
     return router.buildLocation(opts as any)
   }, [router, currentLocation, _options])
 
-  // History-aware links: when `preferBack` is set and the resolved target is
-  // the previous history entry, a primary click should go back rather than push.
-  // `true`/`'pathname'` match by pathname; `'exact'` also requires search.
-  // Reuses the already-built `next`, so no extra `buildLocation` call.
+  // History-aware: go back instead of pushing when the target is the previous
+  // entry. `'exact'` also matches search. Reuses `next`, so no extra buildLocation.
   const isBackNavigation =
     !!preferBack &&
     resolveIsBackNavigation(
@@ -641,10 +639,8 @@ export function useLinkProps<
         setIsTransitioning(false)
       })
 
-      // History-aware: the target is the previous history entry, so go back
-      // instead of pushing. This preserves forward history and the browser's
-      // native per-entry scroll restoration. Scroll/viewTransition behavior is
-      // handled by the router's existing popstate handling.
+      // Target is the previous entry — pop instead of pushing to preserve forward
+      // history and native scroll restoration (handled via the router's popstate).
       if (isBackNavigation) {
         router.history.back({ ignoreBlocker })
         return

packages/react-router/src/useIsBackNavigation.ts

@@ -18,13 +18,9 @@ import type {
 export type BackNavigationMatch = 'pathname' | 'exact'
 
 /**
- * Decide whether navigating to `target` would land on the *previous* history
- * entry, meaning a `history.back()` is preferable to a push.
- *
- * Pure and framework-agnostic: it relies only on the router's in-memory
- * per-index entry tracking (`router.getHistoryEntry`). Returns `false` at the
- * start of history (index 0) and when the previous entry is unknown (e.g. a
- * fresh page load or deep link), so callers degrade gracefully to a normal push.
+ * Whether navigating to `target` lands on the previous history entry (so a
+ * `history.back()` is preferable to a push). Returns `false` at index 0 or when
+ * the previous entry is unknown, so callers degrade gracefully to a push.
  */
 export function resolveIsBackNavigation(
   router: AnyRouter,
@@ -41,22 +37,17 @@ export function resolveIsBackNavigation(
 }
 
 /**
- * Returns `true` when a link/navigation to the given options would resolve to
- * the *previous* history entry — i.e. clicking it should go "back" rather than
- * push a new entry.
- *
- * This is the primitive behind the `preferBack` prop on `Link`. Use it directly
- * when building custom links or buttons that want the same history-aware
- * behavior. It returns `false` on the server and falls back to `false` whenever
- * the previous entry is unknown to the router, so it is always safe to branch on.
+ * Returns `true` when navigating to the given options would resolve to the
+ * previous history entry — i.e. it should go "back" rather than push. The
+ * primitive behind `preferBack`, for use in custom links or buttons.
  *
- * Pass `match: 'exact'` to also require the search to match (defaults to
- * `'pathname'`, which restores the previous entry's exact search and scroll).
+ * Returns `false` on the server and whenever the previous entry is unknown, so
+ * it's always safe to branch on. Pass `match: 'exact'` to also require search to
+ * match (defaults to `'pathname'`).
  *
  * @example
  * const isBack = useIsBackNavigation({ to: '/issues' })
- * // isBack === true  -> call router.history.back()
- * // isBack === false -> navigate normally
+ * // isBack ? router.history.back() : router.navigate({ to: '/issues' })
  */
 export function useIsBackNavigation<
   TRouter extends AnyRouter = RegisteredRouter,

packages/router-core/src/link.ts

@@ -692,24 +692,9 @@ export interface LinkOptionsProps {
    */
   preloadIntentProximity?: number
   /**
-   * Makes the link history-aware: when its resolved target matches the previous
-   * history entry, clicking it calls `history.back()` instead of pushing a new
-   * entry. This preserves forward history and the browser's native per-entry
-   * scroll restoration (typical for "Back to X" links).
-   *
-   * Controls how the target is matched against the previous entry:
-   * - `false` (default) — disabled; behaves like a normal link.
-   * - `true` / `'pathname'` — match by **pathname** only, so a plain
-   *   `<Link to="/x" preferBack>` pops back to the previous `/x` entry and
-   *   restores its exact search params and scroll position.
-   * - `'exact'` — match by **pathname + search**, so the link only goes back
-   *   when its resolved search also equals the previous entry's.
-   *
-   * It is best-effort: the link falls back to a normal push (or replace, if `replace`
-   * is also set) when the target does not match the previous entry, or when the
-   * previous entry is unknown to the router (e.g. a fresh page load or deep link).
-   * The element always renders a real `<a href>`, so keyboard navigation, "copy
-   * link", and middle/modifier-click (open in new tab) keep working.
+   * Makes the link history-aware: when its target is the previous history entry,
+   * clicking goes back instead of pushing (preserving forward history + scroll).
+   * `'exact'` also requires search to match; falls back to a normal push otherwise.
    * @default false
    */
   preferBack?: boolean | 'pathname' | 'exact'

packages/router-core/src/router.ts

@@ -957,19 +957,17 @@ declare global {
 }
 
 /**
- * A snapshot of a history entry the router has visited, keyed by its
- * `__TSR_index`. Used to reconstruct navigation direction (e.g. whether a
- * link's target is the previous entry) since the browser only exposes the
- * current entry.
+ * A visited history entry keyed by its `__TSR_index`, used to resolve navigation
+ * direction (the browser only exposes the current entry).
  */
 export interface RouterHistoryEntry {
   /** The entry's `__TSR_index` in the history stack. */
   index: number
-  /** The parsed (basepath-stripped) pathname, comparable to `buildLocation().pathname`. */
+  /** Parsed (basepath-stripped) pathname, comparable to `buildLocation().pathname`. */
   pathname: string
-  /** The search string including the leading `?`, comparable to `buildLocation().searchStr`. */
+  /** Search string incl. leading `?`, comparable to `buildLocation().searchStr`. */
   searchStr: string
-  /** The full href (pathname + search + hash), without origin. */
+  /** Full href (pathname + search + hash), without origin. */
   href: string
 }
 
@@ -1025,13 +1023,9 @@ export class RouterCore<
   latestLocation!: ParsedLocation<FullSearchSchema<TRouteTree>>
   pendingBuiltLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>
   /**
-   * In-memory map of visited history entries keyed by their `__TSR_index`.
-   *
-   * The browser only ever exposes the *current* history entry, so to answer
-   * "what was the previous entry?" (used by history-aware links via
-   * {@link getHistoryEntry}) the router records every location it commits,
-   * keyed by index. Maintained from {@link updateLatestLocation}, the single
-   * place `latestLocation` is recomputed from history.
+   * Visited history entries keyed by `__TSR_index` (recorded in
+   * {@link updateLatestLocation}), so the router can resolve the previous entry —
+   * which the browser doesn't expose. Read via {@link getHistoryEntry}.
    */
   historyEntries = new Map<number, RouterHistoryEntry>()
   basepath!: string
@@ -1266,14 +1260,9 @@ export class RouterCore<
       this.latestLocation,
     )
 
-    // Record the committed entry by its history index. `replace` keeps the same
-    // index, so it overwrites the slot in place; a push after going back reuses
-    // the truncated forward slot and overwrites it on the next call. The
-    // back-navigation decision only ever reads `index - 1` (always the true
-    // previous entry on the current linear branch), so stale higher indices
-    // left behind by truncation are harmless and need no pruning. We store the
-    // parsed (basepath-stripped) pathname so it compares directly against
-    // `buildLocation().pathname`.
+    // Record the committed entry by index. `replace` overwrites the same index;
+    // truncated forward entries are harmless since the back-decision only reads
+    // `index - 1`. Stored pathname/search compare directly with buildLocation().
     const index = this.latestLocation.state.__TSR_index ?? 0
     this.historyEntries.set(index, {
       index,
@@ -1284,12 +1273,9 @@ export class RouterCore<
   }
 
   /**
-   * Look up a previously-visited history entry by its `__TSR_index`.
-   *
-   * Returns `undefined` for entries the router has not seen — e.g. entries that
-   * existed before the app loaded (a fresh page load or deep link). Consumers
-   * such as history-aware links should degrade gracefully when this is
-   * `undefined`.
+   * Look up a visited history entry by its `__TSR_index`. Returns `undefined` for
+   * entries the router never recorded (e.g. a fresh page load or deep link), so
+   * consumers should degrade gracefully.
    */
   getHistoryEntry = (index: number): RouterHistoryEntry | undefined =>
     this.historyEntries.get(index)