Route Loaders

Route loaders are route-level functions that can specify arbitrary data requirements for that route. They can be used to:

• Fetch data from a server
• Delay the loading of a route until an asynchronous action has been completed
• Prepare the route to be rendered

Why should I use route loaders? Why are they cool?!

Routes requiring data are nothing new, but the way React Location orchestrates these requirements is where the magic happens. In a traditional React application, usually, the route is rendered immediately, and the data is fetched asynchronously either via a custom hook or a suspense boundary that is hit. This is a great way to get data from a server, but it also means that the route is rendered before the data is available. It introduces the need for a lot of boilerplate code to handle the asynchronous data fetching and even worse, spinners everywhere. This is usually a sub-optimal user experience, and with route loaders, it's one that we can avoid!

Route loaders are called when:

• A route is matched for navigation
• A route is matched for preloading

Route Loader Promises

Route loaders are extremely agnostic as to how you fetch your data. You can use any data fetching means that you like! Here are some of our favorites:

• fetch
• axios
• React Query
• GraphQL-Request
• Relay
• RTK Query

All you have to do is return a promise that resolves an object with the data you want to be available at the route.

Route Loader Objects

Why do route loaders need to return an object? Because multiple route loaders can be matched at once. For example:

• A teams route might have a route loader that fetches a list of teams
• A teams/:teamId route might have another loader that fetches the individual team details.

At the teams route, you would return an object with the teams key, and at the teams/:teamId route, you would return an object with the team key.

1 const routes = [
2   {
3     path: 'teams',
4     loader: async () => ({
5       teams: await fetch('/api/teams'),
6     }),
7     children: [
8       {
9         path: ':teamId',
10         loader: async ({ params: { teamId } }) => ({
11           team: await fetch(`/api/teams/${teamId}`),
12         }),
13       },
14     ],
15   },
16 ]

Each of these loader objects will be merged together into a single object that can be consumed in your routes or sub-loaders:

1 {
2   "teams": [...],
3   "team": {...}
4 }

Parallelized Execution Vs Serial Execution

Route loaders are parallelized by default. This means that when a route is matched, each of the loaders it matches will be executed at the same time. This is great for performance, but it also means that if one of the loaders fails, the others will still be executed. It also means that if one of your loaders depends on the data of a parent, it will need to de-opt and await the promise of its parent before proceeding.

Here is an example of a route loader that depends on the data of a parent:

1 const routes = [
2   {
3     path: 'teams',
4     loader: async () => ({
5       teams: await fetch('/api/teams'),
6     }),
7     children: [
8       {
9         path: ':teamId',
10         loader: async ({ params: { teamId } }, { parentMatch }) => ({
11           // This route will wait for the parent loaderPromise to resolve before finding the individual team
12           team: await parentMatch.loaderPromise.then(({ teams }) =>
13             teams.find((team) => team.id === teamId)
14           ),
15         }),
16       },
17     ],
18   },
19 ]

Using loader data in Routes with the useMatch hook

Loader data is made available to elements via the useMatch hook. Calling useMatch in an element will return the closest match to the component you call it from:

1 const routes = [
2   {
3     path: 'teams',
4     element: <Teams />,
5     loader: async () => ({
6       teams: await fetch('/api/teams'),
7     }),
8     children: [
9       {
10         path: ':teamId',
11         element: <Team />,
12         loader: async ({ params: { teamId }, parentMatch }) => ({
13           // This route will wait for the parent loaderPromise to resolve before finding the individual team
14           team: await parentMatch.loaderPromise.then(({ teams }) =>
15             teams.find((team) => team.id === teamId)
16           ),
17         }),
18       },
19     ],
20   },
21 ]
22 
23 function Teams() {
24   const {
25     data: { teams },
26   } = useMatch()
27 }
28 
29 function Team() {
30   const {
31     data: { team },
32   } = useMatch()
33 }

Route Loader Caching

The built-in caching mechanisms for React Location are extremely basic on purpose since caching is not the core responsibility or purpose of React Location. That said, it ensures a very good UX out of the box by doing the bare minimum to retain navigational consistency.

By default, route loaders are called for new or changed routes in the route hierarchy that resulted from a navigation.

Given the following navigational hierarchy, the bolded routes will have their route loaders called:

1. /dashboard
2. /dashboard, /accounts
3. /dashboard, /accounts, /customers /123
4. /dashboard, /accounts, /customers /456
5. /dashboard, /accounts, /dashboard
6. /dashboard, /accounts
7. /dashboard

As you might have noticed, only the new or changed route loaders were called during navigation and not the old ones. This is because route loader results are cached if they do not change from navigation to navigation.

Even as the session navigated back up to /dashboard, each of the parent route loaders were not called again, but cached and reused.

Cache Max Age

The maxAge of a route loader represents the amount of time in milliseconds to cache the result of the route loader. After this duration, the route loader will be called again to retrieve a fresh result. The maxAge of a route loader can be configured in the following ways, each one overriding the next:

• Dispatching a maxAge event from the loader using the loader dispatcher
• Passing a maxAge option to useLoadRoute() when prefetching
• Passing a loaderMaxAge option to the route definition itself
• Passing a defaultLoaderMaxAge to the Router component

Loader Dispatcher

The loader dispatcher can be used to imperatively update specific aspects of a router loader's state either during or after the loader has run. This can be useful for:

• Setting a maxAge for the route loader based on the loader response
• Triggering background refetches of a route loader
• Extending the cache abilities of a route loader, as is done with the react-location-simple-cache package.

The dispatcher can be accessed in the second options bag argument of the loader function:

1 const routes = [{
2   path: 'teams',
3   loader: async (match, { dispatch }) => {
4     // dispatch(event)
5     ...
6   },
7 }]

The dispatcher takes an event object as its only argument. The event object must have a type property and any additional properties that correspond to that event. Here is the event type:

1 export type LoaderDispatchEvent<
2   TGenerics extends PartialGenerics = DefaultGenerics
3 > =
4   | {
5       type: 'maxAge'
6       maxAge: number
7     }
8   | {
9       type: 'loading'
10     }
11   | {
12       type: 'resolve'
13       data: UseGeneric<TGenerics, 'LoaderData'>
14     }
15   | {
16       type: 'reject'
17       error: unknown
18     }

• The maxAge event can be used to set the maxAge of a route loader based on data from inside the loader function, like a response from a server!
• The loading event can be used to indicate that the route loader is in a loading state.
• The resolve event can be used to indicate that the route loader has completed successfully and is required to pass the new loader data.
• The reject event can be used to indicate that the route loader has failed and is required to pass the error that caused the failure.

Here's an example of using a Response's max-age header to set the maxAge for the loader:

1 const routes = [
2   {
3     path: 'teams',
4     loader: async (_match, { dispatch }) => {
5       const teamsRes = await fetch('/api/teams')
6 
7       dispatch({
8         type: 'maxAge',
9         maxAge: Number(teamsRes.headers.get('max-age')),
10       })
11 
12       return {
13         teams: await teamsRes.json(),
14       }
15     },
16   },
17 ]

Handling Loader Errors

Errors caught from the loader function promise are stored in the match state for you to handle in your errorElement route element.

To access the error, you can use the error property on the match state:

1 const routes = [
2   {
3     path: 'teams',
4     loader: async () => {
5       throw new Error('Something went wrong!')
6     },
7     errorElement: <TeamsError />,
8   },
9 ]
10 
11 function TeamsError() {
12   const { error } = useMatch()
13 
14   return (
15     <div>
16       <div>Couldn't load teams!</div>
17       <div>{error.message}</div>
18     </div>
19   )
20 }

Pending States

Route loaders and async elements both share a set of features to show pending states. Because they are shared, we have a dedicated Pending States section where you can learn more about them.