Step Navigation

Step navigation is the breadcrumb trail rendered in the Admin Panel header. In a Custom View, use SetStepNav or useStepNav to populate that existing interface—you do not need to render another breadcrumb component.

Import

1import { SetStepNav, type StepNavItem, useStepNav } from '@payloadcms/ui'

Custom View usage

Use SetStepNav when the complete breadcrumb trail is known while rendering the Custom View.

Loading component example…

SetStepNav renders no visible element itself. It updates the step navigation provider that surrounds Admin Panel views, and the header displays the resulting items.

Define a static nav array outside the component when its contents do not change. This keeps the array reference stable and avoids updating the context after every render.

Use useStepNav when breadcrumb items depend on state that changes while the view remains mounted.

1'use client'
2
3import { useEffect } from 'react'
4import { useStepNav } from '@payloadcms/ui'
5
6export function OrderView({ orderNumber }: { orderNumber: string }) {
7  const { setStepNav } = useStepNav()
8
9  useEffect(() => {
10    setStepNav([
11      { label: 'Orders', url: '/admin/collections/orders' },
12      { label: `Order #${orderNumber}` },
13    ])
14  }, [orderNumber, setStepNav])
15
16  return <h1>Order #{orderNumber}</h1>
17}

Prefer SetStepNav unless you need direct access to the current stepNav value or need to update it in response to local state.

StepNavItem

Each item contains a label and may contain a url.

Property	Type	Description
`label` *	`StaticLabel \| LabelFunction \| JSX.Element`	Displays the translated or custom breadcrumb label.
`url`	`string`	Makes a non-current breadcrumb item navigable when present.

The final item represents the current location and is rendered as text. Earlier items with a url are rendered as links.

* An asterisk denotes that a property is required.

SetStepNav props

These are the props accepted by SetStepNav.

Prop	Type	Default	Description
`nav` *	`StepNavItem[]`	—	Replaces the items displayed in the Admin header.

* An asterisk denotes that a prop is required.

Accessibility

Use short labels that identify each level in the current hierarchy.
Keep the current location as the final item.
Provide URLs for earlier items when users can safely return to those views.
Avoid duplicating the current page heading in every breadcrumb level.

Provider requirements

SetStepNav and useStepNav depend on the step navigation provider already included in the Payload Admin Panel. Use them within an Admin Panel Custom Component or Custom View. Outside that context, setting the navigation is a no-op.

See Custom Views for configuring a view in the Admin Panel.

Was this page helpful?

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.