81 lines
3.4 KiB
Text
81 lines
3.4 KiB
Text
---
|
|
title: Intercepting Routes
|
|
description: Use intercepting routes to load a new route within the current layout while masking the browser URL, useful for advanced routing patterns such as modals.
|
|
related:
|
|
title: Next Steps
|
|
description: Learn how to use modals with Intercepted and Parallel Routes.
|
|
links:
|
|
- app/building-your-application/routing/parallel-routes
|
|
---
|
|
|
|
Intercepting routes allows you to load a route within the current layout while keeping the context for the current page. This routing paradigm can be useful when you want to "intercept" a certain route to show a different route.
|
|
|
|
For example, when clicking on a photo from within a feed, a modal overlaying the feed should show up with the photo. In this case, Next.js intercepts the `/feed` route and "masks" this URL to show `/photo/123` instead.
|
|
|
|
<Image
|
|
alt="Intercepting routes soft navigation"
|
|
srcLight="/docs/light/intercepting-routes-soft-navigate.png"
|
|
srcDark="/docs/dark/intercepting-routes-soft-navigate.png"
|
|
width="1600"
|
|
height="617"
|
|
/>
|
|
|
|
However, when navigating to the photo directly by for example when clicking a shareable URL or by refreshing the page, the entire photo page should render instead of the modal. No route interception should occur.
|
|
|
|
<Image
|
|
alt="Intercepting routes hard navigation"
|
|
srcLight="/docs/light/intercepting-routes-hard-navigate.png"
|
|
srcDark="/docs/dark/intercepting-routes-hard-navigate.png"
|
|
width="1600"
|
|
height="604"
|
|
/>
|
|
|
|
## Convention
|
|
|
|
Intercepting routes can be defined with the `(..)` convention, which is similar to relative path convention `../` but for segments.
|
|
|
|
You can use:
|
|
|
|
- `(.)` to match segments on the **same level**
|
|
- `(..)` to match segments **one level above**
|
|
- `(..)(..)` to match segments **two levels above**
|
|
- `(...)` to match segments from the **root** `app` directory
|
|
|
|
For example, you can intercept the `photo` segment from within the `feed` segment by creating a `(..)photo` directory.
|
|
|
|
<Image
|
|
alt="Intercepting routes folder structure"
|
|
srcLight="/docs/light/intercepted-routes-files.png"
|
|
srcDark="/docs/dark/intercepted-routes-files.png"
|
|
width="1600"
|
|
height="604"
|
|
/>
|
|
|
|
> Note that the `(..)` convention is based on _route segments_, not the file-system.
|
|
|
|
## Examples
|
|
|
|
### Modals
|
|
|
|
Intercepting Routes can be used together with [Parallel Routes](/docs/app/building-your-application/routing/parallel-routes) to create modals.
|
|
|
|
Using this pattern to create modals overcomes some common challenges when working with modals, by allowing you to:
|
|
|
|
- Make the modal content **shareable through a URL**
|
|
- **Preserve context** when the page is refreshed, instead of closing the modal
|
|
- **Close the modal on backwards navigation** rather than going to the previous route
|
|
- **Reopen the modal on forwards navigation**
|
|
|
|
<Image
|
|
alt="Intercepting routes modal example"
|
|
srcLight="/docs/light/intercepted-routes-modal-example.png"
|
|
srcDark="/docs/dark/intercepted-routes-modal-example.png"
|
|
width="1600"
|
|
height="976"
|
|
/>
|
|
|
|
> In the above example, the path to the `photo` segment can use the `(..)` matcher since `@modal` is a _slot_ and not a _segment_. This means that the `photo` route is only one _segment_ level higher, despite being two _file-system_ levels higher.
|
|
|
|
Other examples could include opening a login modal in a top navbar while also having a dedicated `/login` page, or opening a shopping cart in a side modal.
|
|
|
|
[View an example](https://github.com/vercel-labs/nextgram) of modals with Intercepted and Parallel Routes.
|