useSelectedLayoutSegments

useSelectedLayoutSegments is a Client Component hook that lets you read the active route segments below the Layout it is called from.

It is useful for creating UI in parent Layouts that need knowledge of active child segments such as breadcrumbs.

'use client'
 
import { useSelectedLayoutSegments } from 'next/navigation'
 
export default function ExampleClientComponent() {
  const segments = useSelectedLayoutSegments()
 
  return (
    <ul>
      {segments.map((segment, index) => (
        <li key={index}>{segment}</li>
      ))}
    </ul>
  )
}

Parameters

const segments = useSelectedLayoutSegments(parallelRoutesKey?: string)

useSelectedLayoutSegments optionally accepts a parallelRoutesKey, which allows you to read the active route segment within that slot.

Returns

useSelectedLayoutSegments returns an array of strings containing the active segments one level down from the layout the hook was called from. Or an empty array if none exist.

For example, given the Layouts and URLs below, the returned segments would be:

For catch-all routes ([...slug]), all matched path segments are returned as a single joined string within the array:

Behavior

Cache Components

When cacheComponents is enabled, useSelectedLayoutSegments may require a Suspense boundary. This depends on whether the active segments can be resolved during prerendering.

• Static routes and routes with generateStaticParams: every route segment, including dynamic params, is known at build time. The active segments can be resolved during prerendering, so useSelectedLayoutSegments resolves on the server and no Suspense boundary is required.
• Routes with dynamic params not covered by generateStaticParams: the param is a fallback param that is not known until request time. The active segments cannot be resolved during prerendering, so useSelectedLayoutSegments suspends. Wrap the component (or a parent) in a Suspense boundary so its fallback can be rendered during prerendering; otherwise, the build fails.

This applies even when the component that calls useSelectedLayoutSegments is itself static. For example, a breadcrumb component rendered in a parent layout suspends on any page below it that has an unknown dynamic param. To keep the rest of the layout prerendered, wrap the component that calls useSelectedLayoutSegments (or a parent) in a Suspense boundary with a fallback.

See Next.js encountered URL data in a Client Component outside of Suspense for full fix options and trade-offs.

Version History