Open History to see the last commit
1import {
2 BaseRootRoute,
3 BaseRoute,
4 BaseRouteApi,
5 notFound,
6} from '@tanstack/router-core'
7import React from 'react'
8import { useLoaderData } from './useLoaderData'
9import { useLoaderDeps } from './useLoaderDeps'
10import { useParams } from './useParams'
11import { useSearch } from './useSearch'
12import { useNavigate } from './useNavigate'
13import { useMatch } from './useMatch'
14import { useRouteContext } from './useRouteContext'
15import { useRouter } from './useRouter'
16import { Link } from './link'
17import type {
18 AnyContext,
19 AnyRoute,
20 AnyRouter,
21 ConstrainLiteral,
22 ErrorComponentProps,
23 NotFoundError,
24 NotFoundRouteProps,
25 Register,
26 RegisteredRouter,
27 ResolveFullPath,
28 ResolveId,
29 ResolveParams,
30 RootRoute as RootRouteCore,
31 RootRouteId,
32 RootRouteOptions,
33 RouteConstraints,
34 Route as RouteCore,
35 RouteIds,
36 RouteMask,
37 RouteOptions,
38 RouteTypesById,
39 RouterCore,
40 ToMaskOptions,
41 UseNavigateResult,
42} from '@tanstack/router-core'
43import type { UseLoaderDataRoute } from './useLoaderData'
44import type { UseMatchRoute } from './useMatch'
45import type { UseLoaderDepsRoute } from './useLoaderDeps'
46import type { UseParamsRoute } from './useParams'
47import type { UseSearchRoute } from './useSearch'
48import type { UseRouteContextRoute } from './useRouteContext'
49import type { LinkComponentRoute } from './link'
50β
51declare module '@tanstack/router-core' {
52 export interface UpdatableRouteOptionsExtensions {
53 component?: RouteComponent
54 errorComponent?: false | null | undefined | ErrorRouteComponent
55 notFoundComponent?: NotFoundRouteComponent
56 pendingComponent?: RouteComponent
57 }
58β
59 export interface RootRouteOptionsExtensions {
60 shellComponent?: ({
61 children,
62 }: {
63 children: React.ReactNode
64 }) => React.ReactNode
65 }
66β
67 export interface RouteExtensions<
68 in out TId extends string,
69 in out TFullPath extends string,
70 > {
71 useMatch: UseMatchRoute<TId>
72 useRouteContext: UseRouteContextRoute<TId>
73 useSearch: UseSearchRoute<TId>
74 useParams: UseParamsRoute<TId>
75 useLoaderDeps: UseLoaderDepsRoute<TId>
76 useLoaderData: UseLoaderDataRoute<TId>
77 useNavigate: () => UseNavigateResult<TFullPath>
78 Link: LinkComponentRoute<TFullPath>
79 }
80}
81β
82/**
83 * Returns a route-specific API that exposes type-safe hooks pre-bound
84 * to a single route ID. Useful for consuming a route's APIs from files
85 * where the route object isn't directly imported (e.g. code-split files).
86 *
87 * @param id Route ID string literal for the target route.
88 * @returns A `RouteApi` instance bound to the given route ID.
89 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/getRouteApiFunction
90 */
91export function getRouteApi<
92 const TId,
93 TRouter extends AnyRouter = RegisteredRouter,
94>(id: ConstrainLiteral<TId, RouteIds<TRouter['routeTree']>>) {
95 return new RouteApi<TId, TRouter>({ id })
96}
97β
98export class RouteApi<
99 TId,
100 TRouter extends AnyRouter = RegisteredRouter,
101> extends BaseRouteApi<TId, TRouter> {
102 /**
103 * @deprecated Use the `getRouteApi` function instead.
104 */
105 constructor({ id }: { id: TId }) {
106 super({ id })
107 }
108β
109 useMatch: UseMatchRoute<TId> = (opts) => {
110 return useMatch({ ...opts, from: this.id } as any) as any
111 }
112β
113 useRouteContext: UseRouteContextRoute<TId> = (opts) => {
114 return useRouteContext({ ...(opts as any), from: this.id })
115 }
116β
117 useSearch: UseSearchRoute<TId> = (opts) => {
118 return useSearch({ ...opts, from: this.id } as any)
119 }
120β
121 useParams: UseParamsRoute<TId> = (opts) => {
122 return useParams({ ...opts, from: this.id } as any)
123 }
124β
125 useLoaderDeps: UseLoaderDepsRoute<TId> = (opts) => {
126 return useLoaderDeps({ ...opts, from: this.id, strict: false } as any)
127 }
128β
129 useLoaderData: UseLoaderDataRoute<TId> = (opts) => {
130 return useLoaderData({ ...opts, from: this.id, strict: false } as any)
131 }
132β
133 useNavigate = (): UseNavigateResult<
134 RouteTypesById<TRouter, TId>['fullPath']
135 > => {
136 const router = useRouter()
137 return useNavigate({ from: router.routesById[this.id as string].fullPath })
138 }
139β
140 notFound = (opts?: NotFoundError) => {
141 return notFound({ routeId: this.id as string, ...opts })
142 }
143β
144 Link: LinkComponentRoute<RouteTypesById<TRouter, TId>['fullPath']> =
145 React.forwardRef((props, ref: React.ForwardedRef<HTMLAnchorElement>) => {
146 const router = useRouter()
147 const fullPath = router.routesById[this.id as string].fullPath
148 return <Link ref={ref} from={fullPath as never} {...props} />
149 }) as unknown as LinkComponentRoute<
150 RouteTypesById<TRouter, TId>['fullPath']
151 >
152}
153β
154export class Route<
155 in out TRegister = unknown,
156 in out TParentRoute extends RouteConstraints['TParentRoute'] = AnyRoute,
157 in out TPath extends RouteConstraints['TPath'] = '/',
158 in out TFullPath extends RouteConstraints['TFullPath'] = ResolveFullPath<
159 TParentRoute,
160 TPath
161 >,
162 in out TCustomId extends RouteConstraints['TCustomId'] = string,
163 in out TId extends RouteConstraints['TId'] = ResolveId<
164 TParentRoute,
165 TCustomId,
166 TPath
167 >,
168 in out TSearchValidator = undefined,
169 in out TParams = ResolveParams<TPath>,
170 in out TRouterContext = AnyContext,
171 in out TRouteContextFn = AnyContext,
172 in out TBeforeLoadFn = AnyContext,
173 in out TLoaderDeps extends Record<string, any> = {},
174 in out TLoaderFn = undefined,
175 in out TChildren = unknown,
176 in out TFileRouteTypes = unknown,
177 in out TSSR = unknown,
178 in out TServerMiddlewares = unknown,
179 in out THandlers = undefined,
180>
181 extends BaseRoute<
182 TRegister,
183 TParentRoute,
184 TPath,
185 TFullPath,
186 TCustomId,
187 TId,
188 TSearchValidator,
189 TParams,
190 TRouterContext,
191 TRouteContextFn,
192 TBeforeLoadFn,
193 TLoaderDeps,
194 TLoaderFn,
195 TChildren,
196 TFileRouteTypes,
197 TSSR,
198 TServerMiddlewares,
199 THandlers
200 >
201 implements
202 RouteCore<
203 TRegister,
204 TParentRoute,
205 TPath,
206 TFullPath,
207 TCustomId,
208 TId,
209 TSearchValidator,
210 TParams,
211 TRouterContext,
212 TRouteContextFn,
213 TBeforeLoadFn,
214 TLoaderDeps,
215 TLoaderFn,
216 TChildren,
217 TFileRouteTypes,
218 TSSR,
219 TServerMiddlewares,
220 THandlers
221 >
222{
223 /**
224 * @deprecated Use the `createRoute` function instead.
225 */
226 constructor(
227 options?: RouteOptions<
228 TRegister,
229 TParentRoute,
230 TId,
231 TCustomId,
232 TFullPath,
233 TPath,
234 TSearchValidator,
235 TParams,
236 TLoaderDeps,
237 TLoaderFn,
238 TRouterContext,
239 TRouteContextFn,
240 TBeforeLoadFn,
241 TSSR,
242 TServerMiddlewares,
243 THandlers
244 >,
245 ) {
246 super(options)
247 }
248β
249 useMatch: UseMatchRoute<TId> = (opts) => {
250 return useMatch({ ...opts, from: this.id } as any) as any
251 }
252β
253 useRouteContext: UseRouteContextRoute<TId> = (opts?) => {
254 return useRouteContext({ ...(opts as any), from: this.id })
255 }
256β
257 useSearch: UseSearchRoute<TId> = (opts) => {
258 return useSearch({ ...opts, from: this.id } as any)
259 }
260β
261 useParams: UseParamsRoute<TId> = (opts) => {
262 return useParams({ ...opts, from: this.id } as any)
263 }
264β
265 useLoaderDeps: UseLoaderDepsRoute<TId> = (opts) => {
266 return useLoaderDeps({ ...opts, from: this.id } as any)
267 }
268β
269 useLoaderData: UseLoaderDataRoute<TId> = (opts) => {
270 return useLoaderData({ ...opts, from: this.id } as any)
271 }
272β
273 useNavigate = (): UseNavigateResult<TFullPath> => {
274 return useNavigate({ from: this.fullPath })
275 }
276β
277 Link: LinkComponentRoute<TFullPath> = React.forwardRef(
278 (props, ref: React.ForwardedRef<HTMLAnchorElement>) => {
279 return <Link ref={ref} from={this.fullPath as never} {...props} />
280 },
281 ) as unknown as LinkComponentRoute<TFullPath>
282}
283β
284/**
285 * Creates a non-root Route instance for code-based routing.
286 *
287 * Use this to define a route that will be composed into a route tree
288 * (typically via a parent route's `addChildren`). If you're using file-based
289 * routing, prefer `createFileRoute`.
290 *
291 * @param options Route options (path, component, loader, context, etc.).
292 * @returns A Route instance to be attached to the route tree.
293 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createRouteFunction
294 */
295export function createRoute<
296 TRegister = unknown,
297 TParentRoute extends RouteConstraints['TParentRoute'] = AnyRoute,
298 TPath extends RouteConstraints['TPath'] = '/',
299 TFullPath extends RouteConstraints['TFullPath'] = ResolveFullPath<
300 TParentRoute,
301 TPath
302 >,
303 TCustomId extends RouteConstraints['TCustomId'] = string,
304 TId extends RouteConstraints['TId'] = ResolveId<
305 TParentRoute,
306 TCustomId,
307 TPath
308 >,
309 TSearchValidator = undefined,
310 TParams = ResolveParams<TPath>,
311 TRouteContextFn = AnyContext,
312 TBeforeLoadFn = AnyContext,
313 TLoaderDeps extends Record<string, any> = {},
314 TLoaderFn = undefined,
315 TChildren = unknown,
316 TSSR = unknown,
317 const TServerMiddlewares = unknown,
318>(
319 options: RouteOptions<
320 TRegister,
321 TParentRoute,
322 TId,
323 TCustomId,
324 TFullPath,
325 TPath,
326 TSearchValidator,
327 TParams,
328 TLoaderDeps,
329 TLoaderFn,
330 AnyContext,
331 TRouteContextFn,
332 TBeforeLoadFn,
333 TSSR,
334 TServerMiddlewares
335 >,
336): Route<
337 TRegister,
338 TParentRoute,
339 TPath,
340 TFullPath,
341 TCustomId,
342 TId,
343 TSearchValidator,
344 TParams,
345 AnyContext,
346 TRouteContextFn,
347 TBeforeLoadFn,
348 TLoaderDeps,
349 TLoaderFn,
350 TChildren,
351 TSSR,
352 TServerMiddlewares
353> {
354 return new Route<
355 TRegister,
356 TParentRoute,
357 TPath,
358 TFullPath,
359 TCustomId,
360 TId,
361 TSearchValidator,
362 TParams,
363 AnyContext,
364 TRouteContextFn,
365 TBeforeLoadFn,
366 TLoaderDeps,
367 TLoaderFn,
368 TChildren,
369 TSSR,
370 TServerMiddlewares
371 >(
372 // TODO: Help us TypeChris, you're our only hope!
373 options as any,
374 )
375}
376β
377export type AnyRootRoute = RootRoute<
378 any,
379 any,
380 any,
381 any,
382 any,
383 any,
384 any,
385 any,
386 any,
387 any,
388 any
389>
390β
391/**
392 * Creates a root route factory that requires a router context type.
393 *
394 * Use when your root route expects `context` to be provided to `createRouter`.
395 * The returned function behaves like `createRootRoute` but enforces a context type.
396 *
397 * @returns A factory function to configure and return a root route.
398 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createRootRouteWithContextFunction
399 */
400export function createRootRouteWithContext<TRouterContext extends {}>() {
401 return <
402 TRegister = Register,
403 TRouteContextFn = AnyContext,
404 TBeforeLoadFn = AnyContext,
405 TSearchValidator = undefined,
406 TLoaderDeps extends Record<string, any> = {},
407 TLoaderFn = undefined,
408 TSSR = unknown,
409 TServerMiddlewares = unknown,
410 >(
411 options?: RootRouteOptions<
412 TRegister,
413 TSearchValidator,
414 TRouterContext,
415 TRouteContextFn,
416 TBeforeLoadFn,
417 TLoaderDeps,
418 TLoaderFn,
419 TSSR,
420 TServerMiddlewares
421 >,
422 ) => {
423 return createRootRoute<
424 TRegister,
425 TSearchValidator,
426 TRouterContext,
427 TRouteContextFn,
428 TBeforeLoadFn,
429 TLoaderDeps,
430 TLoaderFn,
431 TSSR,
432 TServerMiddlewares
433 >(options)
434 }
435}
436β
437/**
438 * @deprecated Use the `createRootRouteWithContext` function instead.
439 */
440export const rootRouteWithContext = createRootRouteWithContext
441β
442export class RootRoute<
443 in out TRegister = unknown,
444 in out TSearchValidator = undefined,
445 in out TRouterContext = {},
446 in out TRouteContextFn = AnyContext,
447 in out TBeforeLoadFn = AnyContext,
448 in out TLoaderDeps extends Record<string, any> = {},
449 in out TLoaderFn = undefined,
450 in out TChildren = unknown,
451 in out TFileRouteTypes = unknown,
452 in out TSSR = unknown,
453 in out TServerMiddlewares = unknown,
454 in out THandlers = undefined,
455>
456 extends BaseRootRoute<
457 TRegister,
458 TSearchValidator,
459 TRouterContext,
460 TRouteContextFn,
461 TBeforeLoadFn,
462 TLoaderDeps,
463 TLoaderFn,
464 TChildren,
465 TFileRouteTypes,
466 TSSR,
467 TServerMiddlewares,
468 THandlers
469 >
470 implements
471 RootRouteCore<
472 TRegister,
473 TSearchValidator,
474 TRouterContext,
475 TRouteContextFn,
476 TBeforeLoadFn,
477 TLoaderDeps,
478 TLoaderFn,
479 TChildren,
480 TFileRouteTypes,
481 TSSR,
482 TServerMiddlewares,
483 THandlers
484 >
485{
486 /**
487 * @deprecated `RootRoute` is now an internal implementation detail. Use `createRootRoute()` instead.
488 */
489 constructor(
490 options?: RootRouteOptions<
491 TRegister,
492 TSearchValidator,
493 TRouterContext,
494 TRouteContextFn,
495 TBeforeLoadFn,
496 TLoaderDeps,
497 TLoaderFn,
498 TSSR,
499 TServerMiddlewares,
500 THandlers
501 >,
502 ) {
503 super(options)
504 }
505β
506 useMatch: UseMatchRoute<RootRouteId> = (opts) => {
507 return useMatch({ ...opts, from: this.id } as any) as any
508 }
509β
510 useRouteContext: UseRouteContextRoute<RootRouteId> = (opts) => {
511 return useRouteContext({ ...(opts as any), from: this.id })
512 }
513β
514 useSearch: UseSearchRoute<RootRouteId> = (opts) => {
515 return useSearch({ ...opts, from: this.id } as any)
516 }
517β
518 useParams: UseParamsRoute<RootRouteId> = (opts) => {
519 return useParams({ ...opts, from: this.id } as any)
520 }
521β
522 useLoaderDeps: UseLoaderDepsRoute<RootRouteId> = (opts) => {
523 return useLoaderDeps({ ...opts, from: this.id } as any)
524 }
525β
526 useLoaderData: UseLoaderDataRoute<RootRouteId> = (opts) => {
527 return useLoaderData({ ...opts, from: this.id } as any)
528 }
529β
530 useNavigate = (): UseNavigateResult<'/'> => {
531 return useNavigate({ from: this.fullPath })
532 }
533β
534 Link: LinkComponentRoute<'/'> = React.forwardRef(
535 (props, ref: React.ForwardedRef<HTMLAnchorElement>) => {
536 return <Link ref={ref} from={this.fullPath} {...props} />
537 },
538 ) as unknown as LinkComponentRoute<'/'>
539}
540β
541/**
542 * Creates a root Route instance used to build your route tree.
543 *
544 * Typically paired with `createRouter({ routeTree })`. If you need to require
545 * a typed router context, use `createRootRouteWithContext` instead.
546 *
547 * @param options Root route options (component, error, pending, etc.).
548 * @returns A root route instance.
549 * @link https://tanstack.com/router/latest/docs/framework/react/api/router/createRootRouteFunction
550 */
551export function createRootRoute<
552 TRegister = Register,
553 TSearchValidator = undefined,
554 TRouterContext = {},
555 TRouteContextFn = AnyContext,
556 TBeforeLoadFn = AnyContext,
557 TLoaderDeps extends Record<string, any> = {},
558 TLoaderFn = undefined,
559 TSSR = unknown,
560 const TServerMiddlewares = unknown,
561 THandlers = undefined,
562>(
563 options?: RootRouteOptions<
564 TRegister,
565 TSearchValidator,
566 TRouterContext,
567 TRouteContextFn,
568 TBeforeLoadFn,
569 TLoaderDeps,
570 TLoaderFn,
571 TSSR,
572 TServerMiddlewares,
573 THandlers
574 >,
575): RootRoute<
576 TRegister,
577 TSearchValidator,
578 TRouterContext,
579 TRouteContextFn,
580 TBeforeLoadFn,
581 TLoaderDeps,
582 TLoaderFn,
583 unknown,
584 unknown,
585 TSSR,
586 TServerMiddlewares,
587 THandlers
588> {
589 return new RootRoute<
590 TRegister,
591 TSearchValidator,
592 TRouterContext,
593 TRouteContextFn,
594 TBeforeLoadFn,
595 TLoaderDeps,
596 TLoaderFn,
597 unknown,
598 unknown,
599 TSSR,
600 TServerMiddlewares,
601 THandlers
602 >(options)
603}
604β
605export function createRouteMask<
606 TRouteTree extends AnyRoute,
607 TFrom extends string,
608 TTo extends string,
609>(
610 opts: {
611 routeTree: TRouteTree
612 } & ToMaskOptions<RouterCore<TRouteTree, 'never', boolean>, TFrom, TTo>,
613): RouteMask<TRouteTree> {
614 return opts as any
615}
616β
617export interface DefaultRouteTypes<TProps> {
618 component:
619 | ((props: TProps) => any)
620 | React.LazyExoticComponent<(props: TProps) => any>
621}
622export interface RouteTypes<TProps> extends DefaultRouteTypes<TProps> {}
623β
624export type AsyncRouteComponent<TProps> = RouteTypes<TProps>['component'] & {
625 preload?: () => Promise<void> | undefined
626}
627β
628export type RouteComponent = AsyncRouteComponent<{}>
629β
630export type ErrorRouteComponent = AsyncRouteComponent<ErrorComponentProps>
631β
632export type NotFoundRouteComponent = RouteTypes<NotFoundRouteProps>['component']
633β
634export class NotFoundRoute<
635 TRegister,
636 TParentRoute extends AnyRootRoute,
637 TRouterContext = AnyContext,
638 TRouteContextFn = AnyContext,
639 TBeforeLoadFn = AnyContext,
640 TSearchValidator = undefined,
641 TLoaderDeps extends Record<string, any> = {},
642 TLoaderFn = undefined,
643 TChildren = unknown,
644 TSSR = unknown,
645 TServerMiddlewares = unknown,
646> extends Route<
647 TRegister,
648 TParentRoute,
649 '/404',
650 '/404',
651 '404',
652 '404',
653 TSearchValidator,
654 {},
655 TRouterContext,
656 TRouteContextFn,
657 TBeforeLoadFn,
658 TLoaderDeps,
659 TLoaderFn,
660 TChildren,
661 TSSR,
662 TServerMiddlewares
663> {
664 constructor(
665 options: Omit<
666 RouteOptions<
667 TRegister,
668 TParentRoute,
669 string,
670 string,
671 string,
672 string,
673 TSearchValidator,
674 {},
675 TLoaderDeps,
676 TLoaderFn,
677 TRouterContext,
678 TRouteContextFn,
679 TBeforeLoadFn,
680 TSSR,
681 TServerMiddlewares
682 >,
683 | 'caseSensitive'
684 | 'parseParams'
685 | 'stringifyParams'
686 | 'path'
687 | 'id'
688 | 'params'
689 >,
690 ) {
691 super({
692 ...(options as any),
693 id: '404',
694 })
695 }
696}