2020-01-03 19:16:51 +01:00
---
description: Next.js has a built-in, opinionated, and file-system based Router. You can learn how it works here.
---
2019-12-23 16:07:38 +01:00
# Routing
Next.js has a file-system based router built on the [concept of pages ](/docs/basic-features/pages.md ).
2021-11-15 15:37:08 +01:00
When a file is added to the `pages` directory, it's automatically available as a route.
2019-12-23 16:07:38 +01:00
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
2021-11-15 15:37:08 +01:00
The router supports nested files. If you create a nested folder structure, files will automatically be routed in the same way still.
2019-12-23 16:07:38 +01:00
- `pages/blog/first-post.js` → `/blog/first-post`
- `pages/dashboard/settings/username.js` → `/dashboard/settings/username`
#### Dynamic route segments
2021-11-15 15:37:08 +01:00
To match a dynamic segment, you can use the bracket syntax. This allows you to match named parameters.
2019-12-23 16:07:38 +01:00
- `pages/blog/[slug].js` → `/blog/:slug` (`/blog/hello-world`)
- `pages/[username]/settings.js` → `/:username/settings` (`/foo/settings`)
2020-01-24 04:41:48 +01:00
- `pages/post/[...all].js` → `/post/*` (`/post/2020/id/title`)
2019-12-23 16:07:38 +01:00
2020-09-07 18:35:30 +02:00
> Check out the [Dynamic Routes documentation](/docs/routing/dynamic-routes.md) to learn more about how they work.
2019-12-23 16:07:38 +01:00
## Linking between pages
2020-12-14 09:55:52 +01:00
The Next.js router allows you to do client-side route transitions between pages, similar to a single-page application.
2019-12-23 16:07:38 +01:00
2020-04-17 16:26:25 +02:00
A React component called `Link` is provided to do this client-side route transition.
2019-12-23 16:07:38 +01:00
```jsx
import Link from 'next/link'
function Home() {
return (
< ul >
< li >
< Link href = "/" >
< a > Home< / a >
< / Link >
< / li >
< li >
< Link href = "/about" >
< a > About Us< / a >
< / Link >
< / li >
2020-09-07 18:35:30 +02:00
< li >
< Link href = "/blog/hello-world" >
< a > Blog Post< / a >
< / Link >
< / li >
2019-12-23 16:07:38 +01:00
< / ul >
)
}
export default Home
```
2021-11-15 15:37:08 +01:00
The example above uses multiple links. Each one maps a path (`href`) to a known page:
2020-09-07 18:35:30 +02:00
- `/` → `pages/index.js`
- `/about` → `pages/about.js`
- `/blog/hello-world` → `pages/blog/[slug].js`
2022-01-29 03:52:40 +01:00
Any `<Link />` in the viewport (initially or through scroll) will be prefetched by default (including the corresponding data) for pages using [Static Generation ](/docs/basic-features/data-fetching/get-static-props.md ). The corresponding data for [server-rendered ](/docs/basic-features/data-fetching/get-server-side-props.md ) routes is _not_ prefetched.
2021-03-02 04:17:43 +01:00
2020-09-07 18:35:30 +02:00
### Linking to dynamic paths
2019-12-23 16:07:38 +01:00
2020-09-07 18:35:30 +02:00
You can also use interpolation to create the path, which comes in handy for [dynamic route segments ](#dynamic-route-segments ). For example, to show a list of posts which have been passed to the component as a prop:
2019-12-23 16:07:38 +01:00
```jsx
import Link from 'next/link'
2020-09-07 18:35:30 +02:00
function Posts({ posts }) {
2019-12-23 16:07:38 +01:00
return (
< ul >
2020-09-07 18:35:30 +02:00
{posts.map((post) => (
< li key = {post.id} >
< Link href = {`/blog/${encodeURIComponent(post.slug)}`} >
< a > {post.title}< / a >
< / Link >
< / li >
))}
2019-12-23 16:07:38 +01:00
< / ul >
)
}
2020-09-07 18:35:30 +02:00
export default Posts
2019-12-23 16:07:38 +01:00
```
2020-09-07 18:35:30 +02:00
> [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) is used in the example to keep the path utf-8 compatible.
Alternatively, using a URL Object:
2020-04-06 13:36:57 +02:00
```jsx
2020-09-07 18:35:30 +02:00
import Link from 'next/link'
function Posts({ posts }) {
2020-04-06 13:36:57 +02:00
return (
< ul >
2020-05-18 21:24:37 +02:00
{posts.map((post) => (
2020-04-06 13:36:57 +02:00
< li key = {post.id} >
2020-09-07 18:35:30 +02:00
< Link
href={{
pathname: '/blog/[slug]',
query: { slug: post.slug },
}}
>
2020-04-06 13:36:57 +02:00
< a > {post.title}< / a >
< / Link >
< / li >
))}
< / ul >
)
}
2020-09-07 18:35:30 +02:00
export default Posts
2020-04-06 13:36:57 +02:00
```
2020-09-07 18:35:30 +02:00
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.
2019-12-23 16:07:38 +01:00
## Injecting the router
< details >
< summary > < b > Examples< / b > < / summary >
< ul >
2020-05-27 23:51:11 +02:00
< li > < a href = "https://github.com/vercel/next.js/tree/canary/examples/dynamic-routing" > Dynamic Routing< / a > < / li >
2019-12-23 16:07:38 +01:00
< / ul >
< / details >
To access the [`router` object ](/docs/api-reference/next/router.md#router-object ) in a React component you can use [`useRouter` ](/docs/api-reference/next/router.md#useRouter ) or [`withRouter` ](/docs/api-reference/next/router.md#withRouter ).
In general we recommend using [`useRouter` ](/docs/api-reference/next/router.md#useRouter ).
## Learn more
The router is divided in multiple parts:
< div class = "card" >
< a href = "/docs/api-reference/next/link.md" >
< b > next/link:< / b >
< small > Handle client-side navigations.< / small >
< / a >
< / div >
< div class = "card" >
< a href = "/docs/api-reference/next/router.md" >
< b > next/router:< / b >
< small > Leverage the router API in your pages.< / small >
< / a >
< / div >