Routing

Next.js has a file-system based router built on the concept of pages.

When a file is added to the pages directory, it’s automatically available as a route.

The files inside the pages directory can be used to define most common patterns.

Index routes

The router will automatically route files named index to the root of the directory.

  • pages/index.js/
  • pages/blog/index.js/blog

Nested routes

The router supports nested files. If you create a nested folder structure, files will automatically be routed in the same way still.

  • pages/blog/first-post.js/blog/first-post
  • pages/dashboard/settings/username.js/dashboard/settings/username

Dynamic route segments

To match a dynamic segment, you can use the bracket syntax. This allows you to match named parameters.

  • pages/blog/[slug].js/blog/:slug (/blog/hello-world)
  • pages/[username]/settings.js/:username/settings (/foo/settings)
  • pages/post/[...all].js/post/* (/post/2020/id/title)

Check out the Dynamic Routes documentation to learn more about how they work.

Linking between pages

The Next.js router allows you to do client-side route transitions between pages, similar to a single-page application.

A React component called Link is provided to do this client-side route transition.

  1. import Link from 'next/link'
  2. function Home() {
  3. return (
  4. <ul>
  5. <li>
  6. <Link href="/">
  7. <a>Home</a>
  8. </Link>
  9. </li>
  10. <li>
  11. <Link href="/about">
  12. <a>About Us</a>
  13. </Link>
  14. </li>
  15. <li>
  16. <Link href="/blog/hello-world">
  17. <a>Blog Post</a>
  18. </Link>
  19. </li>
  20. </ul>
  21. )
  22. }
  23. export default Home

The example above uses multiple links. Each one maps a path (href) to a known page:

  • /pages/index.js
  • /aboutpages/about.js
  • /blog/hello-worldpages/blog/[slug].js

Any <Link /> in the viewport (initially or through scroll) will be prefetched by default (including the corresponding data) for pages using Static Generation. The corresponding data for server-rendered routes is not prefetched.

Linking to dynamic paths

You can also use interpolation to create the path, which comes in handy for dynamic route segments. For example, to show a list of posts which have been passed to the component as a prop:

  1. import Link from 'next/link'
  2. function Posts({ posts }) {
  3. return (
  4. <ul>
  5. {posts.map((post) => (
  6. <li key={post.id}>
  7. <Link href={`/blog/${encodeURIComponent(post.slug)}`}>
  8. <a>{post.title}</a>
  9. </Link>
  10. </li>
  11. ))}
  12. </ul>
  13. )
  14. }
  15. export default Posts

encodeURIComponent is used in the example to keep the path utf-8 compatible.

Alternatively, using a URL Object:

  1. import Link from 'next/link'
  2. function Posts({ posts }) {
  3. return (
  4. <ul>
  5. {posts.map((post) => (
  6. <li key={post.id}>
  7. <Link
  8. href={{
  9. pathname: '/blog/[slug]',
  10. query: { slug: post.slug },
  11. }}
  12. >
  13. <a>{post.title}</a>
  14. </Link>
  15. </li>
  16. ))}
  17. </ul>
  18. )
  19. }
  20. export default Posts

Now, instead of using interpolation to create the path, we use a URL object in href where:

  • pathname is the name of the page in the pages directory. /blog/[slug] in this case.
  • query is an object with the dynamic segment. slug in this case.

Injecting the router

Examples

To access the router object in a React component you can use useRouter or withRouter.

In general we recommend using useRouter.

Learn more

The router is divided in multiple parts:

next/linkHandle client-side navigations.

next/routerLeverage the router API in your pages.