Preloading in TanStack Router is a way to load a route before the user actually navigates to it. This is useful for routes that are likely to be visited by the user, but not necessarily on the first page load.
Preloading works by using hover and touch start events on <Link>
components to preload the dependencies for the destination route.
The simplest way to preload routes for your application is to set the preload
option to intent
for your entire router:
import { Router } from '@tanstack/react-router'
const router = new Router({ // ... preload: 'intent',})
This will turn on preloading by default for all <Link>
components in your application. You can also set the preload
prop on individual <Link>
components to override the default behavior.
By default, preloading will start after 50ms of the user hovering or touching a <Link>
component. You can change this delay by setting the preloadDelay
option on your router:
import { Router } from '@tanstack/react-router'
const router = new Router({ // ... preloadDelay: 100,})
You can also set the preloadDelay
prop on individual <Link>
components to override the default behavior on a per-link basis.
Preloading is most useful when combined with the built-in loaders (or your favorite data loading library). To make this easier, the loader
route option function receives a preload
boolean denoting whether the route is being preloaded or not. If you're using the built-in loader state, preload states are already handled for you automatically. If that's not the case, then the preload
flag allows you to load data differently depending on whether the user is navigating to the route or preloading it.
Here's an example using TanStack Loaders:
import { Route } from '@tanstack/react-router'
const postsRoute = new Route({ getParentRoute: () => rootRoute, path: 'posts', component: PostsComponent, loader: async ({ preload }) => { await loaderClient.load({ key: 'posts', preload }) },})
Not all data loading libraries will differentiate between preloading or not, but usually a preload method or option is available and can control different aspects of the actual data fetching or caching strategy of the data. For example, when you pass preload
to TanStack Loaders, the maxAge and maxGcAge are tracked separately from the normal load method (just as they are automatically if you use the built-in route loader state).
If you need to manually preload a route, you can use the router's preloadRoute
method. It accepts a standard TanStack NavigateOptions
object and returns a promise that resolves when the route is preloaded.
function Component() { const router = useRouter()
useEffect(() => { try { router.preloadRoute({ to: postRoute, params: { id: 1 } }) } catch (err) { // Failed to preload route } }, [])
return <div />}
Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.