Parallel Routes

Parallel Routing allows you to simultaneously or conditionally render one or more pages in the same layout. For highly dynamic sections of an app, such as dashboards and feeds on social sites, Parallel Routing can be used to implement complex routing patterns.

For example, you can simultaneously render the team and analytics pages.

Parallel Routing allows you to define independent error and loading states for each route as they're being streamed in independently.

Parallel Routing also allows you to conditionally render a slot based on certain conditions, such as authentication state. This enables fully separated code on the same URL.

Convention

Parallel routes are created using named slots. Slots are defined with the @folder convention, and are passed to the same-level layout as props.

For example, the following file structure defines two explicit slots: @analytics and @team.

The folder structure above means that the component in app/layout.js now accepts the @analytics and @team slots props, and can render them in parallel alongside the children prop:

export default function Layout(props: {
  children: React.ReactNode;
  analytics: React.ReactNode;
  team: React.ReactNode;
}) {
  return (
    <>
      {props.children}
      {props.team}
      {props.analytics}
    </>
  );
}

Unmatched Routes

By default, the content rendered within a slot will match the current URL.

In the case of an unmatched slot, the content that Next.js renders differs based on the routing technique and folder structure.

default.js

You can define a default.js file to render as a fallback when Next.js cannot recover a slot's active state based on the current URL.

Consider the following folder structure. The @team slot has a settings directory, but @analytics does not.

If you were to navigate from the root / to /settings, the content that gets rendered is different based on the type of navigation and the availability of the default.js file.

Soft Navigation

On a soft navigation - Next.js will render the slot's previously active state, even if it doesn't match the current URL.

Hard Navigation

On a hard navigation - a navigation that requires a full page reload - Next.js will first try to render the unmatched slot's default.js file. If that's not available, a 404 gets rendered.

useSelectedLayoutSegment(s)

Both useSelectedLayoutSegment and useSelectedLayoutSegments accept a parallelRoutesKey, which allows you read the active route segment within that slot.

"use client";
 
import { useSelectedLayoutSegment } from "next/navigation";
 
export default async function Layout(props: {
  //...
  authModal: React.ReactNode;
}) {
  const loginSegments = useSelectedLayoutSegment("authModal");
  // ...
}

When a user navigates to @authModal/login, or /login in the URL bar, loginSegments will be equal to the string "login".

Examples

Modals

Parallel Routing can be used to render modals.

The @authModal slot renders a <Modal> component that can be shown by navigating to a matching route, for example /login.

export default async function Layout(props: {
  // ...
  authModal: React.ReactNode;
}) {
  return (
    <>
      {/* ... */}
      {props.authModal}
    </>
  );
}

import { Modal } from "components/modal";
 
export default function Login() {
  return (
    <Modal>
      <h1>Login</h1>
      {/* ... */}
    </Modal>
  );
}

To ensure that the contents of the modal don't get rendered when it's not active, you can create a default.js file that returns null.

export default function Default() {
  return null;
}

Dismissing a modal

If a modal was initiated through client navigation, e.g. by using <Link href="/login">, you can dismiss the modal by calling router.back() or by using a Link component.

"use client";
import { useRouter } from "next/navigation";
import { Modal } from "components/modal";
 
export default async function Login() {
  const router = useRouter();
  return (
    <Modal>
      <span onClick={() => router.back()}>Close modal</span>
      <h1>Login</h1>
      ...
    </Modal>
  );
}

If you want to navigate elsewhere and dismiss a modal, you can also use a catch-all route.

export default function CatchAll() {
  return null;
}

Conditional Routes

Parallel Routes can be used to implement conditional routing. For example, you can render a @dashboard or @login route depending on the authentication state.

import { getUser } from "@/lib/auth";
 
export default function Layout({
  dashboard,
  login,
}: {
  dashboard: React.ReactNode;
  login: React.ReactNode;
}) {
  const isLoggedIn = getUser();
  return isLoggedIn ? dashboard : login;
}