0
Fork 0
mirror of https://github.com/TanStack/router.git synced 2026-11-16 19:38:07 +00:00
router/docs/api/api.md
Tanner Linsley 8fab8b4175 feat: loader + ephemeral loaderData
Breaking Changes:

- `load` has been renamed back (I know...) to `loader`. Don't kill me. This again stays true to the nature of its functionality.
- `loader` can once again return data, but it is stored ephemerally on the route match and re-loaded on every navigation.
- If you choose to store data in `loaderData` from the `loader` function, you'll likely want to employ some level of caching to ensure you're only fetching data when necessary and resolving as early as possible if you have any meaningful cached data to display to the user. TanStack Query is a great tool to do this.
2023-11-29 01:16:52 -07:00

10 KiB

id title
api API Reference

rootRouteWithContext

Use this function to create a root route with a required router context. The resulting function can be used to create a new root route, which will then require that you satisfy this context type when creating a router that uses it.

const createRootRoute = rootRouteWithContext<ContextType>()

const rootRoute = createRootRoute({
  // ...
})

You can also skip the intermediate variable and create a root route directly from the function.

const rootRoute = rootRouteWithContext<ContextType>()({
  // ...
})

RootRoute

Use this class to create a new root route without a required router context. Only use this if you do not plan on supplying a routing context to your router. If you do need a routing context, create a new routing context and use the rootRouteWithContext function and its return function instead.

The root route constructor takes a subset of options from the normal Route class. The path and id options are not required for the root route. See Route for more information.

const rootRoute = new RootRoute({
  // ...
})

Route

Use this class to create a new route.

const myRoute = new Route({
  // REQUIRED - A function that returns the parent route.
  getParentRoute: () => Route | RootRoute,
  // REQUIRED (or an ID) - The path for the route.
  path: string,
  // REQUIRED (or a path) - The ID for the route, if it should not use a path to match its children.
  id: string,
  // A function to validate the search parameters for the route.
  validateSearch: (search: string) => boolean,
  // A function that will run before a route is loaded. If you throw a redirect from this function during a navigation, the location will be updated. If you throw any other error, the route will not be loaded (even preloaded)
  // If you choose to return an object, it will be assigned to this route's `routeContext` value and be merged onto the router's `context` value.
  beforeLoad?: (
    opts: {
      // The parsed path parameters available from this route and its parents.
      params: TAllParams
      // The parsed search parameters available from this route only.
      routeSearch: TSearchSchema
      // The marged and parsed search parameters available from this route and its parents.
      search: TFullSearchSchema
      // The abortController used internally by the router
      abortController: AbortController
      // A boolean indicating whether or not the route is being preloaded.
      preload: boolean
      // The context for this route only.
      routeContext: TContext
      // The merged context for thi,bs route and its parents.
      context: TAllContext
    // TContext extends Record<string, any>
    Promise<TContext> | TContext
  // An async function to load or prepare any required prerequisites for the route.
  loader: (match: {
    // The abortController used internally by the router
    abortController: AbortController
    // A boolean indicating whether or not the route is being preloaded.
    preload: boolean
    // The merged context for this route and its parents.
    context: TAllContext & TOnLoadContext
    // If there is a parent route, this will be a promise that resolves when the parent route has been loaded.
    parentMatchPromise?: Promise<void>
  }) =>
    // The result of the loader function which wil be made available via this routes `useLoaderData` method.
    Promise<LoaderResult>,
  // A function to parse the path parameters for the route from the URL
  parseParams: (rawParams: Record<string, string>) => Record<string, TParams>,
  // A function to stringify the path parameters for the route back to the URL
  stringifyParams: (params: Record<string, TParams>) => Record<string, string>,
  //
  //
  // 🧠: The following options can be set in both the constructor AND via the Route.update method.
  //
  //
  // If true, this route will be matched as case-sensitive
  caseSensitive?: boolean,
  // If true, this route will be forcefully wrapped in a suspense boundary
  wrapInSuspense?: boolean,
  // The content to be rendered when the route is matched. If no component is provided, defaults to `<Outlet />`
  component?: (props: {
    // A function that returns the RouteMatch state for this route.
    useMatch: () => RouteMatch,
    // A function that return the loader return value for this route.
    useLoaderData: () => TLoader,
    // A function that returns the merged search parameters, including parent search parameters for this route.
    useSearch: (opts?: {
      // Defaults to `true`
      // If strict is set to `false`, will allow you to get this route's search parameters from a different route's rendering context
      strict?: TStrict
      // A function to select and subscribe to a subset of the search parameters for this route.
      select?: (search: TSearch) => TSelected
    }) => TStrict extends true ? TSelected : TSelected | undefined,
    // A function that returns the merged path parameters, including parent path parameters for this route.
    useParams: (opts?: {
      // A function to select and subscribe to a subset of the path parameters for this route.
      select?: (params: TDefaultSelected) => TSelected
    }) => TSelected,
    // A function that returns the merged context, including parent context for this route.
    useContext: (opts?: {
      // A function to select and subscribe to a subset of the context for this route.
      select?: (context: TDefaultSelected) => TSelected
    }) => TSelected
  }) => ReactNode,
  // The content to be rendered when the route encounters an error
  errorComponent?: (props: {
    // The error component receives the same props as the `component` option above
  }) => ReactNode,
  // If provided, the content to be rendered when the route is loading. If not provided, the route will suspend until ready to be rendered.
  errorComponent?: (props: {
    // The pending component receives the same props as the `component` option above
  }) => ReactNode,
  // An array of functions that can manipulate search params *before* they are passed to links and navigate calls that match this route.
  preSearchFilters?: ((search: TFullSearchSchema) => TFullSearchSchema)[]
  // An array of functions that can manipulate search params *after* they are passed to links and navigate
  // calls that match this route.
  postSearchFilters?: ((search: TFullSearchSchema) => TFullSearchSchema)[]
  // If an error is encountered in any of the lifecycle methods, this function will be called with the error.
  onError?: (err: any) => void
  // These functions are called as route matches are loaded, stick around and leave the active
  // matches
  onEnter?: (match: AnyRouteMatch) => void
  onTransition?: (match: AnyRouteMatch) => void
  onLeave?: (match: AnyRouteMatch) => void
})

Route.addChildren

The addChildren method is used to add child routes to the current route.

Options

  • children
    • array
    • Required
    • An array of child routes.

Returns

  • Route
  • Returns the current route instance.

Example

const myRoute = new Route({
  path: '/home',
  id: 'homeId',
  component: HomeComponent,
})
myRoute.addChildren([childRoute1, childRoute2])

Route.update

The update method updates the options of the route.

Options

  • options
    • object
    • Required
    • The options to be updated.

Returns

  • Route
  • Returns the current route instance.

Example

const myRoute = new Route({
  path: '/home',
  id: 'homeId',
  component: HomeComponent,
})
myRoute.update({ component: UpdatedHomeComponent })

Route.useMatch

The useMatch method returns the match for the given route.

Options

  • opts
    • object
    • Optional
    • Options for matching.

Returns

  • MatchResult
  • Returns the match result.

Example

const myRoute = new Route({
  path: '/home',
  id: 'homeId',
  component: HomeComponent,
})
const match = myRoute.useMatch({ strict: true })

Route.useLoaderData

The useLoaderData method returns the loader for the given route.

Options

  • opts
    • object
    • Optional
    • Options for retrieving the loader.

Returns

  • LoaderResult
  • Returns the loader result.

Example

const myRoute = new Route({
  path: '/home',
  id: 'homeId',
  component: HomeComponent,
})
const loader = myRoute.useLoaderData({ strict: true })

Route.useContext

The useContext method returns the context for the given route.

Options

  • opts
    • object
    • Optional
    • Options for retrieving the context.

Returns

  • ContextResult
  • Returns the context result.

Example

const myRoute = new Route({
  path: '/home',
  id: 'homeId',
  component: HomeComponent,
})
const context = myRoute.useContext({ strict: true })

Route.useSearch

The useSearch method returns the search parameters for the given route.

Options

  • opts
    • object
    • Optional
    • Options for retrieving the search parameters.

Returns

  • SearchResult
  • Returns the search result.

Example

const myRoute = new Route({
  path: '/home',
  id: 'homeId',
  component: HomeComponent,
})
const search = myRoute.useSearch({ strict: true })

Route.useParams

The useParams method returns the parameters for the given route.

Options

  • opts
    • object
    • Optional
    • Options for retrieving the parameters.

Returns

  • ParamsResult
  • Returns the parameters result.

Example

const myRoute = new Route({
  path: '/home',
  id: 'homeId',
  component: HomeComponent,
})
const params = myRoute.useParams({ strict: true })

lazyRouteComponent

import { lazyRouteComponent } from '@tanstack/react-router'

export const expensiveRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'expensive',
  component: lazyRouteComponent(() => import('./Expensive')),
})

export const expensiveNamedRoute = new Route({
  getParentRoute: () => rootRoute,
  path: 'expensive',
  component: lazyRouteComponent(() => import('./Expensive'), 'Expensive'),
})

Options

  • importer: () => Promise<T>
    • Required
  • namedImport: key of T = "default"

Returns

  • element: RouteComponent