How to Use Parallel Routes in Next.js 13

Parallel routes are a feature in Next.js 13 that allow you to render multiple pages or components simultaneously or conditionally using named slots.
Parallel routes use a special router called the App Router, which matches the URL with the file system and passes the slots as props to the layout component.

Next.js is a popular framework for building React applications that support server-side rendering, static site generation, and incremental static regeneration. One of the features that Next.js introduced in version 13.3 is parallel routes, which allow you to show more than one page in the same view, like with complex dashboards or modals.

In this article, we will explore what parallel routes are, how they work, and how to use them in your Next.js projects. We will also look at some common use cases and challenges that parallel routes can help you solve.

How to Use Parallel Routes in Next.js 13

Table of Contents

What are Parallel Routes?
How do Parallel Routes Work?
How to Use Parallel Routes?
What are Some Use Cases for Parallel Routes?
What are Some Challenges with Parallel Routes?
Frequently Asked Questions
Conclusion

What are Parallel Routes?

Parallel routes are a way of creating dynamic and interactive layouts that can render multiple pages or components simultaneously or conditionally. For example, you can use parallel routes to show a modal on top of another page, or to display different sections of a dashboard side by side.

Parallel routes are created using named slots, which are folders that start with an @ sign. For example, @modal or @sidebar. Slots are not route segments and do not affect the URL structure. They are passed to the same-level layout as props, and can be rendered anywhere inside the layout component.

For example, the following file structure defines two slots: @modal and @sidebar.

app
├── @modal
│   └── page.js
├── @sidebar
│   └── page.js
├── page.js
└── layout.js

The layout component in app/layout.js can access the slots as props and render them accordingly:

export default function Layout(props) {
  return (
    <>
      {props.children}
      {props.sidebar}
      {props.modal}
    </>
  );
}

The slot components in app/@modal/page.js and app/@sidebar/page.js can contain any logic or UI elements that you want to display in the corresponding slots.

How do Parallel Routes Work?

Parallel routes work by using a special router called the App Router, which is available in Next.js 13.3 and above. The App Router is responsible for matching the URL with the file system and rendering the appropriate pages or slots.

The App Router uses a convention-based approach to determine which files to render for a given URL. The convention is as follows:

The App Router looks for a folder named app in the root of your project. This folder contains all the pages and slots that you want to use with parallel routes.
The App Router looks for a file named page.js inside the app folder or any subfolder. This file represents the main page that will be rendered for the URL.
The App Router looks for any folders that start with an @ sign inside the same level as the page.js file. These folders represent the slots that will be rendered alongside the main page.
The App Router passes the slots as props to the layout component, which is either defined in app/layout.js or exported as a getLayout function from the main page component.
The App Router also passes any dynamic segments or query parameters from the URL as props to the main page and slot components.

For example, if you have the following file structure:

app
├── @modal
│   └── page.js
├── @sidebar
│   └── page.js
├── [id]
│   ├── @comments
│   │   └── page.js
│   └── page.js
├── page.js
└── layout.js

And you visit the URL /123?foo=bar, the App Router will render the following components:

The main page component from app/[id]/page.js, with { id: ‘123’, foo: ‘bar’ } as props.
The sidebar slot component from app/@sidebar/page.js, with { id: ‘123’, foo: ‘bar’ } as props.
The modal slot component from app/@modal/page.js, with { id: ‘123’, foo: ‘bar’ } as props.
The comments slot component from app/[id]/@comments/page.js, with { id: ‘123’, foo: ‘bar’ } as props.
The layout component from app/layout.js, with { children, sidebar, modal, comments } as props.

How to Use Parallel Routes?

To use parallel routes in your Next.js project, you need to follow these steps:

Make sure you have Next.js 13.3 or above installed. You can check your Next.js version by running next -v in your terminal.
Create an app folder in the root of your project. This folder will contain all your pages and slots that you want to use with parallel routes.
Create a page.js file inside the app folder or any subfolder. This file will represent the main page that will be rendered for the URL.
Create any folders that start with an @ sign inside the same level as the page.js file. These folders will represent the slots that will be rendered alongside the main page.
Create a page.js file inside each slot folder. This file will contain the logic and UI elements that you want to display in the corresponding slot.
Create a layout.js file inside the app folder or export a getLayout function from the main page component. This file or function will define the layout component that will receive and render the slots as props.
Optionally, create any dynamic segments or catch-all segments by wrapping a folder’s name in square brackets. For example, [id] or […slug]. These folders will allow you to access dynamic parameters from the URL as props in your page and slot components.

What are Some Use Cases for Parallel Routes?

Parallel routes can be useful for creating complex and interactive layouts that require multiple pages or components to be rendered simultaneously or conditionally. Some examples of use cases are:

Dashboards: You can use parallel routes to create a dashboard layout that can display different sections of data or charts side by side. For example, you can have a sidebar slot that shows a menu of options, a main page slot that shows a summary of metrics, and a modal slot that shows a detailed report of a selected metric.
Modals: You can use parallel routes to create a modal layout that can show a popup window on top of another page. For example, you can have a main page slot that shows a list of products, and a modal slot that shows a product detail or a checkout form when a product is clicked.
Tabs: You can use parallel routes to create a tab layout that can switch between different pages or components within the same view. For example, you can have a main page slot that shows a profile page, and a tab slot that shows different sections of the profile, such as posts, photos, or settings.

What are Some Challenges with Parallel Routes?

Parallel routes are a powerful feature, but they also come with some challenges and limitations that you need to be aware of. Some of them are:

SEO: Parallel routes do not affect the URL structure, which means that search engines will not be able to index or crawl the content of your slots separately. If you want to optimize your SEO for your slots, you may need to use other techniques, such as prerendering, sitemaps, or canonical links.
Navigation: Parallel routes do not support browser navigation by default, which means that users will not be able to use the back and forward buttons to navigate between your slots. If you want to enable browser navigation for your slots, you may need to use other techniques, such as query parameters, history API, or custom router events.
Performance: Parallel routes may affect the performance of your application, especially if you have many slots or complex components that need to be rendered at the same time. If you want to improve the performance of your parallel routes, you may need to use other techniques, such as code splitting, lazy loading, or caching.

Frequently Asked Questions

Here are some frequently asked questions about parallel routes in Next.js:

Question: How do I access the slot props in my layout component?

Answer: You can access the slot props in your layout component by using their folder names as prop names. For example, if you have an @modal slot folder, you can access its component as props.modal in your layout component.

Question: How do I pass custom props to my slot components?

Answer: You can pass custom props to your slot components by using the getLayoutProps function in your main page component. This function should return an object with keys matching your slot folder names and values containing the custom props. For example, if you want to pass a title prop to your @modal slot component, you can do something like this:

// app/[id]/page.js
export default function Page(props) {
  // ...
}

export function getLayoutProps() {
  return {
    modal: {
      title: "My Modal",
    },
  };
}

Conclusion

Parallel routes are a new feature in Next.js 13 that allow you to create dynamic and interactive layouts that can render multiple pages or components simultaneously or conditionally. They are useful for creating complex UIs such as dashboards, modals, or tabs. They are created using named slots, which are folders that start with an @ sign and contain a page.js file. Slots are passed as props to the layout component, which can render them anywhere inside the layout. Parallel routes use a special router called the App Router, which matches the URL with the file system and renders the appropriate pages or slots.

Parallel routes also have some challenges and limitations, such as SEO, navigation, and performance. You may need to use other techniques or best practices to overcome these challenges and optimize your parallel routes.

We hope this article has helped you understand what parallel routes are, how they work, and how to use them in your Next.js projects. If you have any questions or feedback, please let us know in the comments below.

Disclaimer: This article is not affiliated with or endorsed by Next.js, Vercel, or any other company or organization mentioned in this article. The information and code examples provided in this article are for educational purposes only and may not be accurate, complete, or up-to-date. The author and publisher of this article are not responsible for any errors, omissions, damages, or losses that may result from using or relying on this article. Please use this article at your own risk and discretion.