API

ReactLocation

Required: true

The foundation of React Location 🚀. An instance of the ReactLocation class is required and must be provided to your application via the Router component.

1 export type ReactLocationOptions<TGenerics> = {
2   // The history object to be used internally by react-location
3   // A history will be created automatically if not provided.
4   history?: BrowserHistory | MemoryHistory | HashHistory
5   stringifySearch?: SearchSerializer
6   parseSearch?: SearchParser
7 }

Example: Basic

1 import { ReactLocation } from '@tanstack/react-location'
2 
3 const reactLocation = new ReactLocation()

Example: Memory History

1 import { createMemoryHistory, ReactLocation } from '@tanstack/react-location'
2 
3 const history = createMemoryHistory()
4 const reactLocation = new ReactLocation({ history })

Router

Required: true

The Router component is the root Provider component for the React Location instance and your route configuration in your app. Render it only once (rendering multiple routers is an anti-pattern, and straight-up not supported for good reason).

• If no children prop is passed, it will default to <Outlet /> which will start rendering your route matches.
• if a children prop is passed, you must eventually render <Outlet /> where you want your routes to start rendering

1 export type RouterProps<TGenerics> = {
2   // An instance of the `ReactLocation` class
3   location: ReactLocation<TGenerics>
4   basepath?: string
5   // Children will default to `<Outlet />` if not provided
6   children?: React.ReactNode
7   // An array of route objects to match
8   routes?: Route<TGenerics>[]
9   filterRoutes?: FilterRoutesFn
10   defaultLinkPreloadMaxAge?: number
11   defaultLoaderMaxAge?: number
12   useErrorBoundary?: boolean
13   defaultElement?: SyncOrAsyncElement<TGenerics>
14   defaultErrorElement?: SyncOrAsyncElement<TGenerics>
15   defaultPendingElement?: SyncOrAsyncElement<TGenerics>
16   defaultPendingMs?: number
17   defaultPendingMinMs?: number
18   caseSensitive?: boolean
19 }

Example: Basic

1 import { ReactLocation, Router } from '@tanstack/react-location'
2 
3 const reactLocation = new ReactLocation()
4 
5 return (
6   <Router
7     location={reactLocation}
8     routes={[
9       {
10         path: '/',
11         element: 'Home on the range!',
12       },
13     ]}
14   />
15 )

Example: With Children

1 import { ReactLocation, Router, Outlet } from '@tanstack/react-location'
2 
3 const reactLocation = new ReactLocation()
4 
5 return (
6   <Router
7     location={reactLocation}
8     routes={[
9       {
10         path: '/',
11         element: 'Home on the range!',
12       },
13     ]}
14   >
15     <div>Header</div>
16     <Outlet />
17   </Router>
18 )

Defining Routes

In React Location, routes are just an array of objects where routes can contain child arrays of more routes. It's a route tree!

For more information on creating routes and how they behave, see the Routes Guide.

Route Properties

1 export type Route<TGenerics extends PartialGenerics = DefaultGenerics> = {
2   // The path to match (relative to the nearest parent `Route` component or root basepath)
3   path?: string
4   // An ID to uniquely identify this route within its siblings. This is only required for routes that *only match on search* or if you have multiple routes with the same path
5   id?: string
6   // If true, this route will be matched as case-sensitive
7   caseSensitive?: boolean
8   // Either (1) an object that will be used to shallowly match the current location's search or (2) A function that receives the current search params and can return truthy if they are matched.
9   search?: SearchPredicate<UseGeneric<TGenerics, 'Search'>>
10   // The duration to wait during `loader` execution before showing the `pendingElement`
11   pendingMs?: number
12   // _If the `pendingElement` is shown_, the minimum duration for which it will be visible.
13   pendingMinMs?: number
14   // Search filters can be used to rewrite, persist, default and manipulate search params for link that
15   // point to their routes or child routes. See the "basic" example to see them in action.
16   searchFilters?: SearchFilter<TGenerics>[]
17   // An array of child routes
18   children?: Route<TGenerics>[]
19   // Route Loaders (see below) can be inline on the route, or resolved async
20 } & RouteLoaders<TGenerics> & {
21     // If `import` is defined, this route can resolve its elements and loaders in a single asynchronous call
22     // This is particularly useful for code-splitting or module federation
23     import?: (opts: {
24       params: UseGeneric<TGenerics, 'Params'>
25       search: UseGeneric<TGenerics, 'Search'>
26     }) => Promise<RouteLoaders<TGenerics>>
27   }
28 
29 export type RouteLoaders<TGenerics> = {
30   // The content to be rendered when the route is matched. If no element is provided, defaults to `<Outlet />`
31   element?: SyncOrAsyncElement<TGenerics>
32   // The content to be rendered when `loader` encounters an error
33   errorElement?: SyncOrAsyncElement<TGenerics>
34   // The content to be rendered when the duration of `loader` execution surpasses the `pendingMs` duration
35   pendingElement?: SyncOrAsyncElement<TGenerics>
36   // An asynchronous function responsible for preparing or fetching data for the route before it is rendered
37   loader?: LoaderFn<TGenerics>
38   // An asynchronous function responsible for cleaning up when the match cache is cleared. This is useful when
39   // the loader function has side effects that need to be cleaned up when the match is no longer in use.
40   unloader?: UnloaderFn<TGenerics>
41   // An integer of milliseconds representing how long data should be cached for the route
42   loaderMaxAge?: number
43   // Similar to React's useEffect hook, this function is called
44   // when moving from an inactive state to an active one. Likewise, when moving from
45   // an active to an inactive state, the return function (if provided) is called.
46   onMatch?: (
47     match: RouteMatch<TGenerics>,
48   ) => void | undefined | ((match: RouteMatch<TGenerics>) => void)
49   // This function is called when the route remains active from one transition to the next.
50   onTransition?: (match: RouteMatch<TGenerics>) => void
51   // An object of whatever you want! This object is accessible anywhere matches are.
52   meta?: UseGeneric<TGenerics, 'RouteMeta'>
53 }
54 
55 export type SearchFilter<TGenerics> = (
56   search: UseGeneric<TGenerics, 'Search'>,
57 ) => UseGeneric<TGenerics, 'Search'>

Example - Route Params

1 const routes: Route[] = [
2   {
3     path: 'invoices',
4     children: [
5       {
6         path: '/',
7         element: 'This would render at the `/invoices` path',
8       },
9       {
10         path: 'new',
11         element: `This would render at the '/invoices/new' path`,
12       },
13       {
14         path: ':invoiceId',
15         element: <Invoice />,
16       },
17     ],
18   },
19 ]

Example - Default / Fallback Route

1 const routes: Route[] = [
2   {
3     path: '/',
4   },
5   {
6     path: 'about',
7   },
8   {
9     // Passing no route is equivalent to passing `path: '*'`
10     element: `This would render as the fallback when '/' or '/about' were not matched`,
11   },
12 ]

Example - Default / Fallback Route with client-side redirect

1 const routes: Route[] = [
2   {
3     path: '/',
4     element: 'I am groot!',
5   },
6   {
7     path: 'about',
8     element: 'About me.',
9   },
10   {
11     element: <Navigate to="/" />,
12   },
13 ]

Example - Root Wrapper

1 const routes: Route[] = [
2   {
3     // Defaults to:
4     // path: '*'
5     // element: <Outlet />
6     loader: () => Promise.resolve({ data: 'some global data' }),
7     children: [
8       {
9         path: '/',
10         element: 'I am groot!',
11       },
12       {
13         path: 'about',
14         element: 'About me.',
15       },
16       {
17         element: <Navigate to="/" />,
18       },
19     ],
20   },
21 ]

Example - Data Loaders

1 const routes: Route[] = [
2   {
3     path: '/',
4     element: <Home />,
5   },
6   {
7     path: 'dashboard',
8     element: <Dashboard />,
9   },
10   {
11     path: 'invoices',
12     element: <Invoices />,
13     // Load invoices before rendering
14     loader: async () => ({
15       invoices: await fetchInvoices(),
16     }),
17     children: [
18       {
19         path: 'new',
20         element: <NewInvoice />,
21       },
22       {
23         path: ':invoiceId',
24         element: <Invoice />,
25         // Load the individual invoice before rendering
26         loader: async ({ params }) => ({
27           invoice: await fetchInvoiceById(params.invoiceId),
28         }),
29       },
30     ],
31   },
32 ]

Example - Code Splitting

1 const routes: Route[] = [
2   {
3     path: '/',
4     element: <Home />,
5   },
6   {
7     path: 'expensive',
8     // Code-split Element
9     element: () => import('./Expensive').then((mod) => <mod.default />),
10     // Code-split Loader
11     loader: async (...args) =>
12       import('./Expensive').then((mod) => mod.loader(...args)),
13   },
14 ]

useMatch

The useMatch hook returns the nearest current route match within the context of where it's called. It can be used to access:

• Route Data
• Route Params (eg. /:invoiceId => params.invoiceId)
• The next child match, if applicable

Example - Route Data

1 function App() {
2   return (
3     <Router
4       routes={[
5         {
6           path: 'invoices',
7           element: <Invoices />,
8           loader: async () => ({
9             invoices: await fetchInvoices(),
10           }),
11           children: [
12             {
13               path: ':invoiceId',
14               element: <Invoice />,
15               loader: async ({ params }) => ({
16                 invoice: await fetchInvoiceById(params.invoiceId),
17               }),
18             },
19           ],
20         },
21       ]}
22     />
23   )
24 }
25 
26 function Invoice() {
27   const {
28     data: {
29       // You can access any data merged in from parent loaders as well
30       invoices,
31       invoice,
32     },
33   } = useMatch()
34 }

Example - Route Params

1 function App() {
2   return (
3     <Router
4       routes={[
5         {
6           path: 'invoices',
7           element: <Invoices />,
8           children: [
9             {
10               path: ':invoiceId',
11               element: <Invoice />,
12             },
13           ],
14         },
15       ]}
16     />
17   )
18 }
19 
20 function Invoice() {
21   const {
22     params: { invoiceId },
23   } = useMatch()
24 
25   // Use it for whatever, like in a React Query!
26   const invoiceQuery = useQuery(
27     ['invoices', invoiceId],
28     fetchInvoiceById(invoiceId),
29   )
30 }

useMatches

The useMatches hook is similar to the useMatch hook, except it returns an array of all matches from the current match down. If you are looking for a list of all matches, you'll want to use useRouter().matches.

Example - Route Data

1 function Invoice() {
2   const matches = useMatches()
3 }

Search Params

In React Location, search params are considered first-class objects that can be immutably updated safely and consistently in a similar fashion to React.useStates setState(replacementObj) and setState((old) => new) patterns.

Parsing & Serialization

The first level of search params always have standard encoding, eg. ?param1=value&param2=value&param3=value. This keeps things at the root level of the search params experience fully compliant with the native URLSearchParams API and the rest of the web ecosystem. When it comes to the values of those URLSearchParams, however, React Location offers much more power by fully supporting JSON, included nested JSON structures.

For every search param value, React Location follows the following schema:

• Top-level, primitive, non-object-like values are serialized normally as strings/numbers/booleans.
• Top-level object-like values are serialized using JSON.stringify and parsed using JSON.parse

Custom stringifySearch and parseSearch functions can be provided to your ReactLocation instance to further enhance the way search objects are encoded.

Regardless of how your search params are serialized or parsed, React Location willl always provide a stable, immutable and structurally-safe object reference. This means that even though your search params' source of truth is technically a string that is changing over time, it will behave as a structurally shared immutable object.

Search Param Parsing and Serialization

When implementing custom search param parsing and serialization, the parseSearch/stringifySearch options and parseSearchWith/stringifySearchWith functions will come in handy.

Their types are as follows:

1 export type SearchParser = (searchStr: string) => Record<string, any>
2 export type SearchSerializer = (searchObj: Record<string, any>) => string
3 
4 export function parseSearchWith(
5   parser: (str: string) => any,
6 ): (searchStr: string) => Record<string, any>
7 
8 export function stringifySearchWith(
9   stringify: (search: any) => string,
10 ): (search: Record<string, any>) => string

While unnecessary, here is an example of how to re-implement the default search param parsing and serialization for React Location:

1 import {
2   ReactLocation,
3   parseSearchWith,
4   stringifySearchWith,
5 } from '@tanstack/react-location'
6 
7 const reactLocation = new ReactLocation({
8   parseSearch: (search: string) => {
9     return parseSearchWith(JSON.parse)(search)
10   },
11   stringifySearch: (search: any) => {
12     return stringifySearchWith(JSON.stringify)(search)
13   },
14 })

See more examples of custom search param parsing and serialization

useSearch

The useSearch hook provides access to the search params state for the current location. This JSON object is immutable from render to render through structural sharing so any part of it can be safely used for change-detection, even in useEffect/useMemo dependencies.

Example - Basic

1 import { Router, MakeGenerics } from '@tanstack/react-location'
2 
3 type MyLocationGenerics = MakeGenerics<{
4     Search: {
5       pagination?: {
6         index?: number
7         size?: number
8       }
9       filters?: {
10         name?: string
11       }
12       desc?: boolean
13     }
14 }>
15 
16 function MyComponent() {
17   const search = useSearch<MyLocationGenerics>()
18 
19   console.info(search)
20   // {
21   //   pagination: {
22   //     index: 1,
23   //     size: 20
24   //   },
25   //   filter: {
26   //     name: 'tanner'
27   //   },
28   //   desc: true
29   // }
30 }

Example - Updating URL Search Params State

1 type MyLocationGenerics = MakeGenerics<{
2     Search: {
3       pagination?: {
4         index?: number
5         size?: number
6       }
7       filters?: {
8         name?: string
9       }
10       desc?: boolean
11     }
12   }>
13 >
14 
15 
16 function MyComponent() {
17   const navigate = useNavigate<MyLocationGenerics>()
18 
19   const nextPage = () => {
20     navigate({
21       // All typesafe!
22       search: (old) => ({
23         ...old,
24         pagination: {
25           ...old.pagination,
26           index: old.pagination.index + 1,
27         },
28       }),
29     })
30   }
31 
32   // OR use something like immer!
33 
34   const nextPage = () => {
35     navigate({
36       search: (old) =>
37         immer.produce(old, (draft) => {
38           draft.pagination.index++
39         }),
40     })
41   }
42 }

Link

The Link component allows you to generate links for internal navigation, capable of updating the:

• Pathname
• Search Parameters
• Hash
• Push vs. Replace

The links generated by it are designed to work perfectly with Open in new Tab + ctrl + left-click and Open in new window.... They are also capable of receiving "active" props (depending on the activeOptions passed) to decorate the link when the link is currently active relative to the current location.

1 export type LinkProps<TGenerics extends PartialGenerics = DefaultGenerics> =
2   Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href' | 'children'> & {
3     // The absolute or relative destination pathname
4     to?: string | number | null
5     // The new search object or a function to update it
6     search?: true | Updater<UseGeneric<TGenerics, 'Search'>>
7     // The new has string or a function to update it
8     hash?: Updater<string>
9     // Whether to replace the current history stack instead of pushing a new one
10     replace?: boolean
11     // A function that is passed the [Location API](#location-api) and returns additional props for the `active` state of this link. These props override other props passed to the link (`style`'s are merged, `className`'s are concatenated)
12     getActiveProps?: () => Record<string, any>
13     // Defaults to `{ exact: false, includeHash: false }`
14     activeOptions?: ActiveOptions
15     // If set, will preload the linked route on hover and cache it for this many milliseconds in hopes that the user will eventually navigate there.
16     preload?: number
17     // A custom ref prop because of this: https://stackoverflow.com/questions/58469229/react-with-typescript-generics-while-using-react-forwardref/58473012
18     _ref?: React.Ref<HTMLAnchorElement>
19     // If a function is pass as a child, it will be given the `isActive` boolean to aid in further styling on the element it returns
20     children?:
21       | React.ReactNode
22       | ((state: { isActive: boolean }) => React.ReactNode)
23   }
24 
25 export type ActiveOptions = {
26   exact?: boolean
27   includeHash?: boolean
28 }

Example: The basics

1 function App() {
2   return (
3     <div>
4       <Link to="/home">I will navigate to `/home`</Link>
5       <Link to="todos">
6         I will navigate to `./todos`, relative to the current location
7       </Link>
8       <Link to="..">
9         I will navigate up one level in the location hierarchy.
10       </Link>
11       <Link to="." hash="somehash">
12         I will update the hash to `somehash` at the current location
13       </Link>
14       <Link to="/search" search={{ q: 'yes' }}>
15         I will navigate to `/search?q=yes`
16       </Link>
17       <Link
18         to="."
19         search={{
20           someParams: true,
21           otherParams: 'gogogo',
22           object: { nested: { list: [1, 2, 3], hello: 'world' } },
23         }}
24       >
25         I will navigate to the current location +
26         `?someParams=true&otherParams=gogogo&object=~(nested~(list~(~1~2~3)~hello~%27world))`
27       </Link>
28       <Link
29         search={({ removeThis, ...rest }) => ({
30           ...rest,
31           addThis: 'This is new!',
32         })}
33       >
34         I will add `addThis='This is new!' and also remove the `removeThis`
35         param to/from the search params on the current page
36       </Link>
37     </div>
38   )
39 }

Example: Using getActiveProps

The following link will be green with /about as the current location.

1 <Link
2   to="/about"
3   getActiveProps={(location) => ({
4     style: { color: 'green' },
5   })}
6 >
7   About
8 </Link>

Example: Using a child function for further active state customization

The following link will contain an <ActiveIcon/> prefix when active

1 <Link to="/about">
2   {({ isActive }) => {
3     return (
4       <>
5         {isActive ? (
6           <>
7             <ActiveIcon />{' '}
8           </>
9         ) : null}
10         About
11       </>
12     )
13   }}
14 </Link>

Navigate

When rendered, the Navigate component will declaratively and relatively navigate to any route.

1 export type NavigateOptions<
2   TGenerics extends PartialGenerics = DefaultGenerics,
3 > = {
4   // The new relative or absolute pathname
5   to?: string | null
6   // A new search params object, or a function that receives the latest search params object and returns the new one.
7   search?: Updater<UseGeneric<TGenerics, 'Search'>>
8   // The new hash string
9   hash?: Updater<string>
10   // If set to 'true', will replace the current state instead of pushing a new one onto the stack
11   replace?: boolean
12   // If `true`, the new location will replace the current entry in the history stack instead of creating a new one.
13   fromCurrent?: boolean
14   // If set will update the key of the new location
15   key?: string
16   // ADVANCED. Can be used to set the relative origin of the navigation for resolution
17   from?: Partial<Location<TGenerics>>
18 }

Example

1 function App () {
2   return <Navigate to='./about'>
3 }

useNavigate

The useNavigate hook allows you to programmatically navigate your application.

Usage

1 function MyComponent() {
2   const navigate = useNavigate()
3 
4   const onClick = () => {
5     navigate({ to: './about', replace: true })
6   }
7 
8   return <button onClick={onClick}>About</button>
9 }

useMatchRoute

The useMatchRoute hook allows you to programmatically test both relative and absolute paths against the current or pending location. If a path is matched, it will return an object of route params detected, even if this is an empty object. This can be useful for:

• Detecting specific deep-route matches from a layout component
• Determining if a specific route is the next pending location that is being transitioned to

1 function useMatchRoute(): (opts: {
2   to?: string | number | null
3   search?: SearchPredicate<UseGeneric<TGenerics, 'Search'>>
4   fuzzy?: boolean
5   caseSensitive?: boolean
6   pending?: boolean
7 }) => undefined | Params<TGenerics>

Usage

1 function App() {
2   return (
3     <Router
4       routes={[
5         {
6           element: <Root />,
7           children: [
8             {
9               path: '/',
10               element: 'Hello!',
11             },
12             {
13               path: ':teamId',
14               element: 'Hello!',
15             },
16           ],
17         },
18       ]}
19     />
20   )
21 }
22 
23 function Root() {
24   const matchRoute = useMatchRoute()
25 
26   // If the current path is '/'
27   matchRoute({ to: '/' }) // {}
28   matchRoute({ to: ':teamId' }) // undefined
29 
30   // If the current path is `/team-1'
31   matchRoute({ to: '/' }) // undefined
32   matchRoute({ to: '/', fuzzy: true }) // {}
33   matchRoute({ to: '/*' }) // { '*': 'team-1' }
34   matchRoute({ to: ':teamId' }) // { teamId: 'team-1' }
35 
36   // If the pending path is `/team-1`
37   matchRoute({ to: ':teamId' }) // undefined
38   matchRoute({ to: ':teamId', pending: true }) // { teamId: 'team-1' }
39 }

MatchRoute

The MatchRoute component is merely a component-version of useMatchRoute. It takes all of the same options but comes with some different affordances.

• If the options provided do not result in a match, null will be rendered.
• If the options provided do result in a match
  • If children is a React.ReactNode, children will be rendered
  • If children is a function, it will be called with resulting match params, or an empty object if no params were found.

Example: Rendering ellipsis if the pending route matches

1 function Example() {
2   return (
3     <Link to="dashboard">
4       Dashboard{' '}
5       <MatchRoute to="dashboard" pending>
6         ...
7       </MatchRoute>
8     </Link>
9   )
10 }

useRouter

The useRouter hook can be used to gain access to the state of the parent <Router /> component. Its shape looks like this:

1 export type Router<TGenerics extends PartialGenerics = DefaultGenerics> =
2   // The resolved options used in the router
3   RouterProps<TGenerics> & {
4     // The current transition state of location + matches that has been successfully matched and loaded
5     state: TransitionState<TGenerics>
6     // The next/pending transition state of location + matches that is being matched and loaded
7     pending?: TransitionState<TGenerics>
8   }
9 
10 export type TransitionState<TGenerics> = {
11   status: 'pending' | 'ready'
12   location: Location<TGenerics>
13   matches: Match<TGenerics>[]
14 }

useResolvePath

The useResolvePath hook returns a function that can be used to resolve the full path of a relative route, based on where the hook is called in the route hierarchy.

Example

1 function App() {
2   return (
3     <Router
4       routes={[
5         {
6           path: 'workspaces',
7           children: [
8             {
9               path: 'team',
10               element: <Team />,
11             },
12           ],
13         },
14       ]}
15     />
16   )
17 }
18 
19 function Team() {
20   const resolvePath = useResolvePath()
21 
22   const parentPath = resolvePath('..') // /workspace
23   const parentPath = resolvePath('.') // /workspace/team
24   const parentPath = resolvePath('team-1') // /workspace/team/team-1
25 }

usePrompt

The usePrompt hook allows you to programmatically prompt the user with a dialog.

Its syntax looks like this:

 export function usePrompt(message: string, when: boolean | any): void

• Pass the message string to be displayed to the user
• Pass a when boolean (or anything truthy) to conditionally prompt the user

Example

1 function App() {
2   const [isDirty, setDirty] = useState(false)
3 
4   usePrompt(
5     'There are unsaved changes, are you sure you want to leave?',
6     isDirty,
7   )
8 
9   // ...
10 }

Prompt

The Prompt component is merely a component-version of usePrompt. It takes all of the same options, but comes with some different affordances.

Its syntax looks like this:

 export function Prompt(props: { message: string; when: boolean | any }): null

Example

1 function App() {
2   const [isDirty, setDirty] = useState(false)
3 
4   return (
5     <>
6       <Prompt
7         message="There are unsaved changes, are you sure you want to leave?"
8         when={isDirty}
9       />
10       OR
11       <Prompt
12         message="There are unsaved changes, are you sure you want to leave?"
13         when={isDirty}
14       >
15         Anything you want to render here
16       </Prompt>
17       OR
18       {isDirty ? (
19         // when defaults to true with <Prompt>
20         <Prompt message="There are unsaved changes, are you sure you want to leave?" />
21       ) : null}
22     </>
23   )
24 
25   // ...
26 }