Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 36 ยท Pages and Routing

Dynamic Routes and Client-Only Pages

Handle URLs that are not known at build time in Gatsby: client-only routes with [id].js and [...].js, matchPath, the params prop, and how to fetch data in the browser.

Static generation needs to know every URL during the build. But some pages cannot be known in advance: /users/8421, a dashboard behind a login, a search result page. For those, Gatsby has client-only routes. The server serves one shell page, and React decides in the browser what to show based on the URL.

This lesson shows the file naming syntax, how parameters reach your component, how to fall back to a client router with a splat route, and what to avoid. Gatsby code is read-only; stand-ins reproduce the matching logic.

Square brackets: one dynamic segment

A file name wrapped in square brackets is a client-only route with one dynamic segment:

JSX
// src/pages/users/[id].js (real Gatsby, read-only)
import * as React from "react"

const UserPage = ({ params }) => {
  const [user, setUser] = React.useState(null)

  React.useEffect(() => {
    fetch(`/api/users/${params.id}`)
      .then((response) => response.json())
      .then(setUser)
  }, [params.id])

  if (!user) return <p>Loading...</p>
  return <h1>{user.name}</h1>
}

export default UserPage

/users/8421 and /users/alice both show this page, and params.id contains the text from the URL. The HTML contains only the "Loading..." shell; the data arrives in the browser. That is the key difference from {Product.slug} pages, whose content is baked in at build time.

You can use several parameters: src/pages/shop/[category]/[id].js gives params.category and params.id.

Splat routes: the rest of the path

A file named [...].js matches everything below its folder. The remainder is in params["*"]:

JSX
// src/pages/app/[...].js (real Gatsby, read-only)
import * as React from "react"
import { Router } from "@gatsbyjs/reach-router"

const Dashboard = () => <h2>Dashboard</h2>
const Settings = () => <h2>Settings</h2>

const App = () => (
  <Router basepath="/app">
    <Dashboard path="/" />
    <Settings path="/settings" />
  </Router>
)

export default App

Now /app, /app/settings and /app/anything/else all load this one page. Inside it a client-side router (Gatsby bundles Reach Router) chooses the view. This is the typical pattern for an authenticated area: static marketing pages outside /app, a single-page app inside it.

Named splats exist too: [...slug].js provides params.slug.

matchPath in gatsby-node

The same result is available from code with matchPath when you create a page:

JavaScript
// gatsby-node.js (real Gatsby, read-only)
exports.onCreatePage = ({ page, actions }) => {
  if (page.path.match(/^\/app/)) {
    page.matchPath = "/app/*"
    actions.createPage(page)
  }
}

This is the older way, still common in existing projects. File names are simpler for new code.

What client-only routes cost

  • No SEO content. Search engines see the shell, not the data (although modern crawlers do run JavaScript, it is slower and less reliable).
  • Loading states. You must design for the moment before data arrives.
  • No build-time errors. A broken API call only fails for visitors.

Use client-only routes for private, personalized or highly dynamic content. For public content that can be known in advance, create static pages instead. When a page needs fresh data on every request, server-side rendering is the alternative later covered in the rendering chapter.

flowchart TD
  A["Request /users/8421"] --> B["Host serves the shell page<br/>users/[id]"]
  B --> C["React starts in the browser"]
  C --> D["params.id = 8421"]
  D --> E["fetch user data"]
  E --> F["Show the user"]

The shell is static; the content is fetched after load.

Stand-in: matching dynamic and splat paths

This stand-in is not Gatsby's matcher, but it implements the same file-name rules so you can see how params are produced.

JS Stand-in: route matching with params

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: a tiny client router

Inside a splat page, a router picks a view from the rest of the path. This stand-in uses a plain object of handlers.

JS Stand-in: client router inside /app

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Client-only pages are not protected by being hidden. Anyone can download the JavaScript bundle. Always check authentication on the API that returns the data, never only in the React component.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file name matches /users/42 as a client-only route?

    Square brackets mark a dynamic client-only segment; curly braces are for data-driven pages from GraphQL types.
  2. 2. Where does the URL value appear in the component?

    Gatsby passes route parameters as the params prop.
  3. 3. What does src/pages/app/[...].js match?

    A splat matches any depth, and the remainder is available in params.
  4. 4. Why is a client-only page weak for SEO?

    Content fetched in the browser is not in the static HTML, so crawlers may miss it.

Summary

  • [param].js creates a client-only route whose value arrives in params.
  • [...].js is a splat that matches everything beneath a folder; combine it with a client router.
  • matchPath in onCreatePage is the older equivalent.
  • Client-only pages ship a shell and fetch data in the browser, so avoid them for public, searchable content.
  • Protect data on the server, not only in React code.

Next: Link and Navigation