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.
Slots are not route segments and do not affect the URL structure. The file path
/@team/members
would be accessible at/members
.
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}
</>
)
}
Good to know: The
children
prop is an implicit slot that does not need to be mapped to a folder. This meansapp/page.js
is equivalent toapp/@children/page.js
.
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.
Navigation
On navigation, Next.js will render the slot's previously active state, even if it doesn't match the current URL.
Reload
On reload, Next.js will first try to render the unmatched slot's default.js
file. If that's not available, a 404 gets rendered.
The 404 for unmatched routes helps ensure that you don't accidentally render a route that shouldn't be parallel 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: {
//...
auth: React.ReactNode
}) {
const loginSegments = useSelectedLayoutSegment('auth')
// ...
}
When a user navigates to @auth/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 @auth
slot renders a <Modal>
component that can be shown by navigating to a matching route, for example /login
.
export default async function Layout(props: {
// ...
auth: React.ReactNode
}) {
return (
<>
{/* ... */}
{props.auth}
</>
)
}
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>
)
}
More information on modals is covered in the Intercepting Routes section.
If you want to navigate elsewhere and dismiss a modal, you can also use a catch-all route.
export default function CatchAll() {
return null
}
Catch-all routes take precedence over
default.js
.
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
}
Was this helpful?