Dynamic Routing

Suppose that you want to make your site routing a little more flexible. For example, rather than just going straight to a 404 page if the path is not found, you might want to try and guess an appropriate (and valid!) path. This is where dynamic routing comes into play.

🚀 TL;DR Show me the code. Look at the 20-dynamic-routing branch. This site is deployed here.

What’s the Problem?

Suppose that somebody tries to go to the path /what-is-gatsby/ on the site. Now this is not a valid path, so will result in a 404 page. However, there are a number of similar valid paths:

  • /0.1/what-is-gatsby/
  • /0.2/what-is-gatsby/
  • /0.3/what-is-gatsby/
  • /1.0/what-is-gatsby/
  • /1.1/what-is-gatsby/ and
  • /1.2/what-is-gatsby/.

Would it not be better to go to one of these rather than flinging out the 404 page? I certainly think so!

Types of Dynamic Routing

There are two types of dynamic routing in Gatsby:

  1. parameter routes and
  2. splat routes.

We’ll be looking at the latter.

The […].js File

In a Gatsby site, a file named [...].js (or [...].tsx) is used for dynamic routing. The square brackets [...] indicate a catch-all route. This allows you to handle a variety of different URLs with a single file. This is useful for handling cases like:

  • 404 pages;
  • dynamic routes based on data; or
  • any URL patterns that might not be known ahead of time.

Gatsby uses the [...].js file as part of its file-based routing system, where the file and folder structure in the src/pages directory directly translates into routes on the website. So, for example, you could have both a src/pages/[...].js and a src/pages/blog/[...].js.

We’ll create a file at src/pages/[...].js that exports a function, DynamicRoute(), that returns a component, RedirectComponent. The DynamicRoute() function accepts an object, props (of type PageProps, a Gatsby data structure), which has a variety of useful attributes including

  • location (various components of the URL)
  • pageContext and
  • params.

💡 Since we are only using the params attribute we could have used destructuring to extract only this attribute in the function signature.

The Redirect Component

The component RedirectComponent does a few things:

  1. Construct a candidate path using the slug and the latest version.
  2. Check whether the candidate path is a valid path on the site.
  3. If it is valid then navigate to that path.
  4. If it is not valid then navigate to the 404 page.

The component will use useEffect() to perform the actual navigation.

Redirects with Anchors

What if you want to have different redirects linked to specific anchors? For example, redirect #introduction to one URL and #conclusion to another URL? Sadly you cannot handle this on the server because those anchors never make it that far. They are all handled on the client. So if you want to include anchors in your redirects strategy then you’ll need to do it via dynamic routing and client-side redirects.

Do Try This at Home

Let’s give this a try. Go to the site.

  1. Try navigating to any one of the valid paths listed above. For example, try /1.0/what-is-gatsby/.
  2. Now try navigating to a path without a version. For example, try /what-is-gatsby/.

In the second case you will be redirected to the path /1.2/what-is-gatsby/. A loading page might briefly appear while you are being redirected. Before implementing dynamic routing this path would have taken you to the 404 page.


We have taken a look at a simple application of dynamic routing. Using dynamic routes will make the routing on your site more flexible, providing alternative ways for you to send your users to the right content. You can make it as complicated and flexible as you want.

🚀 TL;DR Show me the code. Look at the 20-dynamic-routing branch. This site is deployed here.