@tanstack/react-router 1.88.0 → 1.89.1

package/dist/esm/useMatch.d.ts

@@ -1,6 +1,6 @@
 import { StructuralSharingOption, ValidateSelected } from './structuralSharing.js';
 import { AnyRouter, RegisteredRouter } from './router.js';
-import { MakeRouteMatch } from './Matches.js';
+import { MakeRouteMatch, MakeRouteMatchUnion } from './Matches.js';
 import { StrictOrFrom, ThrowOrOptional } from './utils.js';
 export interface UseMatchBaseOptions<TRouter extends AnyRouter, TFrom, TStrict extends boolean, TThrow, TSelected, TStructuralSharing extends boolean> {
     select?: (match: MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
@@ -8,5 +8,7 @@ export interface UseMatchBaseOptions<TRouter extends AnyRouter, TFrom, TStrict e
 }
 export type UseMatchRoute<out TFrom> = <TRouter extends AnyRouter = RegisteredRouter, TSelected = unknown, TStructuralSharing extends boolean = boolean>(opts?: UseMatchBaseOptions<TRouter, TFrom, true, true, TSelected, TStructuralSharing> & StructuralSharingOption<TRouter, TSelected, TStructuralSharing>) => UseMatchResult<TRouter, TFrom, true, TSelected>;
 export type UseMatchOptions<TRouter extends AnyRouter, TFrom extends string | undefined, TStrict extends boolean, TSelected, TThrow extends boolean, TStructuralSharing extends boolean> = StrictOrFrom<TRouter, TFrom, TStrict> & UseMatchBaseOptions<TRouter, TFrom, TStrict, TThrow, TSelected, TStructuralSharing> & StructuralSharingOption<TRouter, TSelected, TStructuralSharing>;
-export type UseMatchResult<TRouter extends AnyRouter, TFrom, TStrict extends boolean, TSelected> = unknown extends TSelected ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict> : TSelected;
-export declare function useMatch<TRouter extends AnyRouter = RegisteredRouter, TFrom extends string | undefined = undefined, TStrict extends boolean = true, TThrow extends boolean = true, TSelected = unknown, TStructuralSharing extends boolean = boolean>(opts: UseMatchOptions<TRouter, TFrom, TStrict, TSelected, TThrow, TStructuralSharing>): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow>;
+export type UseMatchResult<TRouter extends AnyRouter, TFrom, TStrict extends boolean, TSelected> = unknown extends TSelected ? TStrict extends true ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict> : MakeRouteMatchUnion<TRouter> : TSelected;
+type ThrowConstraint<TStrict extends boolean, TThrow extends boolean> = TStrict extends false ? (TThrow extends true ? never : TThrow) : TThrow;
+export declare function useMatch<TRouter extends AnyRouter = RegisteredRouter, TFrom extends string | undefined = undefined, TStrict extends boolean = true, TThrow extends boolean = true, TSelected = unknown, TStructuralSharing extends boolean = boolean>(opts: UseMatchOptions<TRouter, TFrom, TStrict, TSelected, ThrowConstraint<TStrict, TThrow>, TStructuralSharing>): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow>;
+export {};

package/dist/esm/useMatch.js.map

@@ -1 +1 @@
-{"version":3,"file":"useMatch.js","sources":["../../src/useMatch.tsx"],"sourcesContent":["import * as React from 'react'\nimport invariant from 'tiny-invariant'\nimport { useRouterState } from './useRouterState'\nimport { dummyMatchContext, matchContext } from './matchContext'\nimport type {\n  StructuralSharingOption,\n  ValidateSelected,\n} from './structuralSharing'\nimport type { AnyRouter, RegisteredRouter } from './router'\nimport type { MakeRouteMatch } from './Matches'\nimport type { StrictOrFrom, ThrowOrOptional } from './utils'\n\nexport interface UseMatchBaseOptions<\n  TRouter extends AnyRouter,\n  TFrom,\n  TStrict extends boolean,\n  TThrow,\n  TSelected,\n  TStructuralSharing extends boolean,\n> {\n  select?: (\n    match: MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>,\n  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>\n  shouldThrow?: TThrow\n}\n\nexport type UseMatchRoute<out TFrom> = <\n  TRouter extends AnyRouter = RegisteredRouter,\n  TSelected = unknown,\n  TStructuralSharing extends boolean = boolean,\n>(\n  opts?: UseMatchBaseOptions<\n    TRouter,\n    TFrom,\n    true,\n    true,\n    TSelected,\n    TStructuralSharing\n  > &\n    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,\n) => UseMatchResult<TRouter, TFrom, true, TSelected>\n\nexport type UseMatchOptions<\n  TRouter extends AnyRouter,\n  TFrom extends string | undefined,\n  TStrict extends boolean,\n  TSelected,\n  TThrow extends boolean,\n  TStructuralSharing extends boolean,\n> = StrictOrFrom<TRouter, TFrom, TStrict> &\n  UseMatchBaseOptions<\n    TRouter,\n    TFrom,\n    TStrict,\n    TThrow,\n    TSelected,\n    TStructuralSharing\n  > &\n  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>\n\nexport type UseMatchResult<\n  TRouter extends AnyRouter,\n  TFrom,\n  TStrict extends boolean,\n  TSelected,\n> = unknown extends TSelected\n  ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>\n  : TSelected\n\nexport function useMatch<\n  TRouter extends AnyRouter = RegisteredRouter,\n  TFrom extends string | undefined = undefined,\n  TStrict extends boolean = true,\n  TThrow extends boolean = true,\n  TSelected = unknown,\n  TStructuralSharing extends boolean = boolean,\n>(\n  opts: UseMatchOptions<\n    TRouter,\n    TFrom,\n    TStrict,\n    TSelected,\n    TThrow,\n    TStructuralSharing\n  >,\n): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow> {\n  const nearestMatchId = React.useContext(\n    opts.from ? dummyMatchContext : matchContext,\n  )\n\n  const matchSelection = useRouterState({\n    select: (state: any) => {\n      const match = state.matches.find((d: any) =>\n        opts.from ? opts.from === d.routeId : d.id === nearestMatchId,\n      )\n      invariant(\n        !((opts.shouldThrow ?? true) && !match),\n        `Could not find ${opts.from ? `an active match from \"${opts.from}\"` : 'a nearest match!'}`,\n      )\n\n      if (match === undefined) {\n        return undefined\n      }\n\n      return opts.select ? opts.select(match) : match\n    },\n    structuralSharing: opts.structuralSharing,\n  } as any)\n\n  return matchSelection as any\n}\n"],"names":[],"mappings":";;;;AAqEO,SAAS,SAQd,MAQ6E;AAC7E,QAAM,iBAAiB,MAAM;AAAA,IAC3B,KAAK,OAAO,oBAAoB;AAAA,EAClC;AAEA,QAAM,iBAAiB,eAAe;AAAA,IACpC,QAAQ,CAAC,UAAe;AAChB,YAAA,QAAQ,MAAM,QAAQ;AAAA,QAAK,CAAC,MAChC,KAAK,OAAO,KAAK,SAAS,EAAE,UAAU,EAAE,OAAO;AAAA,MACjD;AACA;AAAA,QACE,GAAG,KAAK,eAAe,SAAS,CAAC;AAAA,QACjC,kBAAkB,KAAK,OAAO,yBAAyB,KAAK,IAAI,MAAM,kBAAkB;AAAA,MAC1F;AAEA,UAAI,UAAU,QAAW;AAChB,eAAA;AAAA,MAAA;AAGT,aAAO,KAAK,SAAS,KAAK,OAAO,KAAK,IAAI;AAAA,IAC5C;AAAA,IACA,mBAAmB,KAAK;AAAA,EAAA,CAClB;AAED,SAAA;AACT;"}
+{"version":3,"file":"useMatch.js","sources":["../../src/useMatch.tsx"],"sourcesContent":["import * as React from 'react'\nimport invariant from 'tiny-invariant'\nimport { useRouterState } from './useRouterState'\nimport { dummyMatchContext, matchContext } from './matchContext'\nimport type {\n  StructuralSharingOption,\n  ValidateSelected,\n} from './structuralSharing'\nimport type { AnyRouter, RegisteredRouter } from './router'\nimport type { MakeRouteMatch, MakeRouteMatchUnion } from './Matches'\nimport type { StrictOrFrom, ThrowOrOptional } from './utils'\n\nexport interface UseMatchBaseOptions<\n  TRouter extends AnyRouter,\n  TFrom,\n  TStrict extends boolean,\n  TThrow,\n  TSelected,\n  TStructuralSharing extends boolean,\n> {\n  select?: (\n    match: MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>,\n  ) => ValidateSelected<TRouter, TSelected, TStructuralSharing>\n  shouldThrow?: TThrow\n}\n\nexport type UseMatchRoute<out TFrom> = <\n  TRouter extends AnyRouter = RegisteredRouter,\n  TSelected = unknown,\n  TStructuralSharing extends boolean = boolean,\n>(\n  opts?: UseMatchBaseOptions<\n    TRouter,\n    TFrom,\n    true,\n    true,\n    TSelected,\n    TStructuralSharing\n  > &\n    StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,\n) => UseMatchResult<TRouter, TFrom, true, TSelected>\n\nexport type UseMatchOptions<\n  TRouter extends AnyRouter,\n  TFrom extends string | undefined,\n  TStrict extends boolean,\n  TSelected,\n  TThrow extends boolean,\n  TStructuralSharing extends boolean,\n> = StrictOrFrom<TRouter, TFrom, TStrict> &\n  UseMatchBaseOptions<\n    TRouter,\n    TFrom,\n    TStrict,\n    TThrow,\n    TSelected,\n    TStructuralSharing\n  > &\n  StructuralSharingOption<TRouter, TSelected, TStructuralSharing>\n\nexport type UseMatchResult<\n  TRouter extends AnyRouter,\n  TFrom,\n  TStrict extends boolean,\n  TSelected,\n> = unknown extends TSelected\n  ? TStrict extends true\n    ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>\n    : MakeRouteMatchUnion<TRouter>\n  : TSelected\n\ntype ThrowConstraint<\n  TStrict extends boolean,\n  TThrow extends boolean,\n> = TStrict extends false ? (TThrow extends true ? never : TThrow) : TThrow\n\nexport function useMatch<\n  TRouter extends AnyRouter = RegisteredRouter,\n  TFrom extends string | undefined = undefined,\n  TStrict extends boolean = true,\n  TThrow extends boolean = true,\n  TSelected = unknown,\n  TStructuralSharing extends boolean = boolean,\n>(\n  opts: UseMatchOptions<\n    TRouter,\n    TFrom,\n    TStrict,\n    TSelected,\n    ThrowConstraint<TStrict, TThrow>,\n    TStructuralSharing\n  >,\n): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow> {\n  const nearestMatchId = React.useContext(\n    opts.from ? dummyMatchContext : matchContext,\n  )\n\n  const matchSelection = useRouterState({\n    select: (state: any) => {\n      const match = state.matches.find((d: any) =>\n        opts.from ? opts.from === d.routeId : d.id === nearestMatchId,\n      )\n      invariant(\n        !((opts.shouldThrow ?? true) && !match),\n        `Could not find ${opts.from ? `an active match from \"${opts.from}\"` : 'a nearest match!'}`,\n      )\n\n      if (match === undefined) {\n        return undefined\n      }\n\n      return opts.select ? opts.select(match) : match\n    },\n    structuralSharing: opts.structuralSharing,\n  } as any)\n\n  return matchSelection as any\n}\n"],"names":[],"mappings":";;;;AA4EO,SAAS,SAQd,MAQ6E;AAC7E,QAAM,iBAAiB,MAAM;AAAA,IAC3B,KAAK,OAAO,oBAAoB;AAAA,EAClC;AAEA,QAAM,iBAAiB,eAAe;AAAA,IACpC,QAAQ,CAAC,UAAe;AAChB,YAAA,QAAQ,MAAM,QAAQ;AAAA,QAAK,CAAC,MAChC,KAAK,OAAO,KAAK,SAAS,EAAE,UAAU,EAAE,OAAO;AAAA,MACjD;AACA;AAAA,QACE,GAAG,KAAK,eAAe,SAAS,CAAC;AAAA,QACjC,kBAAkB,KAAK,OAAO,yBAAyB,KAAK,IAAI,MAAM,kBAAkB;AAAA,MAC1F;AAEA,UAAI,UAAU,QAAW;AAChB,eAAA;AAAA,MAAA;AAGT,aAAO,KAAK,SAAS,KAAK,OAAO,KAAK,IAAI;AAAA,IAC5C;AAAA,IACA,mBAAmB,KAAK;AAAA,EAAA,CAClB;AAED,SAAA;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-router",
-  "version": "1.88.0",
+  "version": "1.89.1",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",

package/src/RouterProvider.tsx

@@ -15,6 +15,7 @@ import type {
 export interface CommitLocationOptions {
   replace?: boolean
   resetScroll?: boolean
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions
   viewTransition?: boolean | ViewTransitionOptions
   /**
    * @deprecated All navigations use React transitions under the hood now

package/src/Transitioner.tsx

@@ -143,10 +143,13 @@ export function Transitioner() {
       }))
 
       if (typeof document !== 'undefined' && (document as any).querySelector) {
-        if (router.state.location.hash !== '') {
+        const hashScrollIntoViewOptions =
+          router.state.location.state.__hashScrollIntoViewOptions ?? true
+
+        if (hashScrollIntoViewOptions && router.state.location.hash !== '') {
           const el = document.getElementById(router.state.location.hash)
           if (el) {
-            el.scrollIntoView()
+            el.scrollIntoView(hashScrollIntoViewOptions)
           }
         }
       }

package/src/history.ts

@@ -4,5 +4,6 @@ declare module '@tanstack/history' {
   interface HistoryState {
     __tempLocation?: HistoryLocation
     __tempKey?: string
+    __hashScrollIntoViewOptions?: boolean | ScrollIntoViewOptions
   }
 }

package/src/link.tsx

@@ -210,6 +210,10 @@ export type NavigateOptions<
 > = ToOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo> & NavigateOptionProps
 
 export interface NavigateOptionProps {
+  // if set to `true`, the router will scroll the element with an id matching the hash into view with default ScrollIntoViewOptions.
+  // if set to `false`, the router will not scroll the element with an id matching the hash into view.
+  // if set to `ScrollIntoViewOptions`, the router will scroll the element with an id matching the hash into view with the provided options.
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions
   // `replace` is a boolean that determines whether the navigation should replace the current history entry or push a new one.
   replace?: boolean
   resetScroll?: boolean
@@ -609,6 +613,7 @@ export function useLinkProps<
     to,
     preload: userPreload,
     preloadDelay: userPreloadDelay,
+    hashScrollIntoView,
     replace,
     startTransition,
     resetScroll,
@@ -806,6 +811,7 @@ export function useLinkProps<
         ...options,
         replace,
         resetScroll,
+        hashScrollIntoView,
         startTransition,
         viewTransition,
         ignoreBlocker,

package/src/router.ts

@@ -313,6 +313,14 @@ export interface RouterOptions<
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaultviewtransition-property)
    */
   defaultViewTransition?: boolean | ViewTransitionOptions
+  /**
+   * The default `hashScrollIntoView` a route should use if no hashScrollIntoView is provided while navigating
+   *
+   * See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) for more information on `ScrollIntoViewOptions`.
+   *
+   * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#defaulthashscrollintoview-property)
+   */
+  defaultHashScrollIntoView?: boolean | ScrollIntoViewOptions
   /**
    * @default 'fuzzy'
    * @link [API Docs](https://tanstack.com/router/latest/docs/framework/react/api/router/RouterOptionsType#notfoundmode-property)
@@ -1809,7 +1817,7 @@ export class Router<
       this.load()
     } else {
       // eslint-disable-next-line prefer-const
-      let { maskedLocation, ...nextHistory } = next
+      let { maskedLocation, hashScrollIntoView, ...nextHistory } = next
 
       if (maskedLocation) {
         nextHistory = {
@@ -1839,6 +1847,9 @@ export class Router<
         }
       }
 
+      nextHistory.state.__hashScrollIntoViewOptions =
+        hashScrollIntoView ?? this.options.defaultHashScrollIntoView ?? true
+
       this.shouldViewTransition = viewTransition
 
       this.history[next.replace ? 'replace' : 'push'](
@@ -1860,6 +1871,7 @@ export class Router<
   buildAndCommitLocation = ({
     replace,
     resetScroll,
+    hashScrollIntoView,
     viewTransition,
     ignoreBlocker,
     href,
@@ -1882,6 +1894,7 @@ export class Router<
       viewTransition,
       replace,
       resetScroll,
+      hashScrollIntoView,
       ignoreBlocker,
     })
   }

package/src/useMatch.tsx

@@ -7,7 +7,7 @@ import type {
   ValidateSelected,
 } from './structuralSharing'
 import type { AnyRouter, RegisteredRouter } from './router'
-import type { MakeRouteMatch } from './Matches'
+import type { MakeRouteMatch, MakeRouteMatchUnion } from './Matches'
 import type { StrictOrFrom, ThrowOrOptional } from './utils'
 
 export interface UseMatchBaseOptions<
@@ -64,9 +64,16 @@ export type UseMatchResult<
   TStrict extends boolean,
   TSelected,
 > = unknown extends TSelected
-  ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>
+  ? TStrict extends true
+    ? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>
+    : MakeRouteMatchUnion<TRouter>
   : TSelected
 
+type ThrowConstraint<
+  TStrict extends boolean,
+  TThrow extends boolean,
+> = TStrict extends false ? (TThrow extends true ? never : TThrow) : TThrow
+
 export function useMatch<
   TRouter extends AnyRouter = RegisteredRouter,
   TFrom extends string | undefined = undefined,
@@ -80,7 +87,7 @@ export function useMatch<
     TFrom,
     TStrict,
     TSelected,
-    TThrow,
+    ThrowConstraint<TStrict, TThrow>,
     TStructuralSharing
   >,
 ): ThrowOrOptional<UseMatchResult<TRouter, TFrom, TStrict, TSelected>, TThrow> {