メインコンテンツまでスキップ

Parallel Routes

Parallel Routesを使用すると、同じレイアウト内で1つ以上のページを同時または条件付きでレンダリングできます。これは、ダッシュボードやソーシャルサイトのフィードなど、アプリの高度に動的なセクションに役立ちます。

たとえば、ダッシュボードを考えると、parallel routesを使用してteamページとanalyticsページを同時にレンダリングできます：

Parallel Routes DiagramParallel Routes Diagram

Slots​

Parallel routesは、名前付きのslotsを使用して作成されます。Slotsは@folder規約で定義されます。たとえば、次のファイル構造は2つのslotsを定義しています：@analyticsと@team：

Parallel Routes File-system StructureParallel Routes File-system Structure

Slotsは共有された親レイアウトにpropsとして渡されます。上記の例では、app/layout.jsのコンポーネントは@analyticsと@teamのslots propsを受け取り、children propと並行してレンダリングできます：

app/layout.tsx
export default function Layout({
  children,
  team,
  analytics,
}: {
  children: React.ReactNode
  analytics: React.ReactNode
  team: React.ReactNode
}) {
  return (
    <>
      {children}
      {team}
      {analytics}
    </>
  )
}

ただし、slotsはroute segmentsではなく、URL構造には影響しません。たとえば、/@analytics/viewsの場合、URLは@analyticsがslotであるため/viewsになります。Slotsは通常のPageコンポーネントと組み合わせて、route segmentに関連付けられた最終ページを形成します。このため、同じroute segmentレベルで別々のstaticとdynamic slotsを持つことはできません。1つのslotが動的である場合、そのレベルのすべてのslotsは動的でなければなりません。

Good to know:

  • children propはフォルダにマッピングする必要のない暗黙のslotです。つまり、app/page.jsはapp/@children/page.jsと同等です。

Active state and navigation​

デフォルトでは、Next.jsは各slotのアクティブなstate（またはサブページ）を追跡します。ただし、slot内でレンダリングされるコンテンツはナビゲーションの種類に依存します：

  • Soft Navigation：クライアントサイドのナビゲーション中、Next.jsはpartial renderを実行し、slot内のサブページを変更し、他のslotのアクティブなサブページを維持します。たとえそれらが現在のURLと一致しなくても。
  • Hard Navigation：フルページロード（ブラウザのリフレッシュ）後、Next.jsは現在のURLと一致しないslotsのアクティブな状態を判断できません。代わりに、未一致のslotsに対してdefault.jsファイルをレンダリングするか、default.jsが存在しない場合は404をレンダリングします。

Good to know:

  • 未一致のroutesに対する404は、意図しないページでparallel routeを誤ってレンダリングしないようにするのに役立ちます。

default.js​

初期ロードまたはフルページリロード時に未一致のslotsのフォールバックとしてレンダリングするために、default.jsファイルを定義できます。

次のフォルダ構造を考えてみましょう。@team slotには/settingsページがありますが、@analyticsにはありません。

Parallel Routes unmatched routesParallel Routes unmatched routes

/settingsにナビゲートすると、@team slotは/settingsページをレンダリングし、@analytics slotの現在アクティブなページを維持します。

リフレッシュ時、Next.jsは@analyticsに対してdefault.jsをレンダリングします。default.jsが存在しない場合は、代わりに404がレンダリングされます。

さらに、childrenは暗黙のslotであるため、Next.jsが親ページのアクティブな状態を回復できない場合にchildrenのフォールバックをレンダリングするためのdefault.jsファイルも作成する必要があります。

useSelectedLayoutSegment(s)​

useSelectedLayoutSegmentとuseSelectedLayoutSegmentsの両方がparallelRoutesKeyパラメータを受け入れ、slot内のアクティブなroute segmentを読み取ることができます。

app/layout.tsx
'use client'

import { useSelectedLayoutSegment } from 'next/navigation'

export default function Layout({ auth }: { auth: React.ReactNode }) {
  const loginSegment = useSelectedLayoutSegment('auth')
  // ...
}

ユーザーがapp/@auth/login（またはURLバーで/login）にナビゲートすると、loginSegmentは文字列"login"と等しくなります。

Examples​

Conditional Routes​

特定の条件（たとえば、ユーザーの役割）に基づいてroutesを条件付きでレンダリングするためにParallel Routesを使用できます。たとえば、/adminまたは/userの役割に対して異なるダッシュボードページをレンダリングするには：

Conditional routes diagramConditional routes diagram
app/dashboard/layout.tsx
import { checkUserRole } from '@/lib/auth'

export default function Layout({
  user,
  admin,
}: {
  user: React.ReactNode
  admin: React.ReactNode
}) {
  const role = checkUserRole()
  return role === 'admin' ? admin : user
}

Tab Groups​

ユーザーがslotを独立してナビゲートできるようにするために、slot内にlayoutを追加できます。これはタブを作成するのに役立ちます。

たとえば、@analytics slotには2つのサブページがあります：/page-viewsと/visitors。

Analytics slot with two subpages and a layoutAnalytics slot with two subpages and a layout

@analytics内で、2つのページ間でタブを共有するためのlayoutファイルを作成します：

app/@analytics/layout.tsx
import Link from 'next/link'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      <nav>
        <Link href="/page-views">Page Views</Link>
        <Link href="/visitors">Visitors</Link>
      </nav>
      <div>{children}</div>
    </>
  )
}

Modals​

Parallel Routesは、Intercepting Routesと組み合わせて使用して、ディープリンクをサポートするモーダルを作成できます。これにより、モーダルを構築する際の一般的な課題を解決できます：

  • モーダルのコンテンツをURLを通じて共有可能にする。
  • ページがリフレッシュされたときにモーダルを閉じるのではなく、コンテキストを保持する。
  • 後方ナビゲーションでモーダルを閉じるのではなく、前のルートに戻る。
  • 前方ナビゲーションでモーダルを再度開く。

次のUIパターンを考えてみましょう。ユーザーはクライアントサイドのナビゲーションを使用してレイアウトからログインモーダルを開くことができ、または別の/loginページにアクセスできます：

Parallel Routes DiagramParallel Routes Diagram

このパターンを実装するには、まずメインのログインページをレンダリングする/loginルートを作成します。

Parallel Routes DiagramParallel Routes Diagram
app/login/page.tsx
import { Login } from '@/app/ui/login'

export default function Page() {
  return <Login />
}

次に、@auth slot内にdefault.jsファイルを追加し、nullを返します。これにより、モーダルがアクティブでないときにレンダリングされないようにします。

app/@auth/default.tsx
export default function Default() {
  return null
}

@auth slot内で、/(.)loginフォルダを更新して/loginルートをインターセプトします。/(.)login/page.tsxファイルに<Modal>コンポーネントとその子をインポートします：

app/@auth/(.)login/page.tsx
import { Modal } from '@/app/ui/modal'
import { Login } from '@/app/ui/login'

export default function Page() {
  return (
    <Modal>
      <Login />
    </Modal>
  )
}

Good to know:

Opening the modal​

これで、Next.jsのrouterを活用してモーダルを開閉できます。これにより、モーダルが開いているときや、後方および前方にナビゲートするときにURLが正しく更新されます。

モーダルを開くには、@auth slotを親レイアウトにpropとして渡し、children propと一緒にレンダリングします。

app/layout.tsx
import Link from 'next/link'

export default function Layout({
  auth,
  children,
}: {
  auth: React.ReactNode
  children: React.ReactNode
}) {
  return (
    <>
      <nav>
        <Link href="/login">Open modal</Link>
      </nav>
      <div>{auth}</div>
      <div>{children}</div>
    </>
  )
}

ユーザーが<Link>をクリックすると、/loginページにナビゲートする代わりにモーダルが開きます。ただし、リフレッシュまたは初期ロード時に/loginにナビゲートすると、ユーザーはメインのログインページに移動します。

Closing the modal​

モーダルを閉じるには、router.back()を呼び出すか、Linkコンポーネントを使用します。

app/ui/modal.tsx
'use client'

import { useRouter } from 'next/navigation'

export function Modal({ children }: { children: React.ReactNode }) {
  const router = useRouter()

  return (
    <>
      <button
        onClick={() => {
          router.back()
        }}
      >
        Close modal
      </button>
      <div>{children}</div>
    </>
  )
}

Linkコンポーネントを使用して、もはや@auth slotをレンダリングすべきでないページからナビゲートする場合、parallel routeがnullを返すコンポーネントに一致することを確認する必要があります。たとえば、ルートページに戻るときは、@auth/page.tsxコンポーネントを作成します：

app/ui/modal.tsx
import Link from 'next/link'

export function Modal({ children }: { children: React.ReactNode }) {
  return (
    <>
      <Link href="/">Close modal</Link>
      <div>{children}</div>
    </>
  )
}
app/@auth/page.tsx
export default function Page() {
  return null
}

または、他のページ（たとえば、/foo、/foo/barなど）にナビゲートする場合は、catch-all slotを使用できます：

app/@auth/[...catchAll]/page.tsx
export default function CatchAll() {
  return null
}

Good to know:

  • @auth slotでcatch-all routeを使用してモーダルを閉じるのは、Active state and navigationで説明されている動作のためです。slotと一致しなくなったルートへのクライアントサイドのナビゲーションは表示されたままになるため、モーダルを閉じるためにnullを返すルートにslotを一致させる必要があります。
  • 他の例としては、ギャラリーで写真モーダルを開き、専用の/photo/[id]ページを持つ、またはサイドモーダルでショッピングカートを開くことが含まれます。
  • Intercepted and Parallel Routesを使用したモーダルの例を表示する。

Loading and Error UI​

Parallel Routesは独立してストリーミングできるため、各ルートに対して独立したエラーとローディング状態を定義できます：

Parallel routes enable custom error and loading statesParallel routes enable custom error and loading states

詳細については、Loading UIおよびError Handlingのドキュメントを参照してください。