Admin UI: Add Navigation component and Page navigation slot

[retrofox]

What?

Adds a navigation prop to Page (@wordpress/admin-ui) for link-based navigation between the sections of a screen, rendered in the page header.

The navigation is configuration-based and rendered by a small internal component (not exported): consumers pass a list of links, the current one, and optionally a custom link component. Each item is a semantic <a> inside a <nav>, with the current one marked via aria-current="page".

Related discussions: #79154, #76709, #77040.

Why?

Several admin screens need to switch between sections/views from the page header.

Today consumers reach for Tabs, but the Tabs (ARIA tablist) pattern is for toggling panels of content within a single view, not for navigating between locations/URLs. Using it for navigation is semantically inappropriate and loses proper link behavior (history, deep-linking, open-in-new-tab, aria-current). This is the problem described in #79154.

This is a minimal, semantically correct step consumers can adopt now, while the more general NavigationMenu discussed in #79154 (built on Base UI, in @wordpress/ui) is designed and built.

How?

Page accepts a navigation object with the list of items (label + href) and the href of the current one:

import { Page } from '@wordpress/admin-ui';

<Page
	title={ __( 'Analytics' ) }
	navigation={ {
		items: [
			{ label: 'Overview', href: '/overview' },
			{ label: 'Products', href: '/products' },
		],
		currentHref: '/overview',
	} }
>
	{ /* section content */ }
</Page>

Implementation notes:

• Semantics: renders <nav><ul><li><a>, not a tablist; the item matching currentHref gets aria-current="page". The list keeps an explicit role="list" so Safari announces it as a list despite list-style: none.
• Items render with Link (variant="unstyled") from @wordpress/ui, which carries the design-system keyboard focus ring. The scroll container reserves room for the ring so overflow clipping never cuts it off.
• The nav landmark label defaults to "Sections" and is configurable through ariaLabel. The default avoids the word "navigation", per the APG landmark guidance.
• Decoupled from @wordpress/route (per Admin UI: Decouple Page component from @wordpress/route #77040): plain anchors by default, no router dependency in the package. Client-side routing integrates through the top-level components prop on Page; components.link receives standard <a> attributes, with href required:

<Page
	components={ {
		link: ( props ) => <MyRouterLink { ...props } />,
	} }
	navigation={ { items, currentHref } }
>

• navigation is a public data-only config (items, currentHref, ariaLabel); renderer concerns (linkComponent, className) stay internal to the private Navigation component.

• Items meet the 44x44px target size (WCAG 2.5.5 Target Size, Enhanced). The current item takes a stronger foreground tone and heavier weight (design system interactive tokens), with no underline indicator.

• Dev-only validation throws on a missing or duplicate href, so exactly one item can carry aria-current="page".

• Lives in the sticky header, so it inherits the header's scroll behavior. On overflow, it scrolls horizontally rather than wrapping.

• The navigation component is internal, configured only through <Page navigation>, and future-compatible with the eventual NavigationMenu.

Testing Instructions

Storybook:

npm run storybook:dev

Open Admin UI / Page (WithNavigation, WithInteractiveNavigation, WithNavigationAndActions, and FullHeader) and verify:

• Items render as links; the current one is visually distinct and exposes aria-current="page" (check the DOM / an a11y tool).
• In WithInteractiveNavigation, clicking a link moves the current item without a page reload (custom components.link).
• Keyboard focus moves through the links with a visible focus ring, not clipped by the scroll container.
• Narrowing the viewport scrolls the navigation horizontally instead of wrapping.
• VoiceOver in Safari announces the list and its items.

Unit tests:

npm run test:unit packages/admin-ui/src/navigation packages/admin-ui/src/page

Out of scope (follow-ups)

• Per-item icons and a count/badge suffix.
• Nested items / dropdowns / vertical orientation.
• The generic @wordpress/ui NavigationMenu (Design System: Add a dedicated Navigation component #79154) and migrating existing Tabs-as-navigation usages, plus lint guidance.

Types of changes

New feature (non-breaking). Adds a new optional Page prop; existing usage is unaffected.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: retrofox <retrofox@git.wordpress.org>
Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: louwie17 <louwie17@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Size Change: +3.19 kB (+0.04%)

Total Size: 7.72 MB

📦 View Changed

Filename	Size	Change
build/modules/boot/index.min.js	51.4 kB	+1.88 kB (+3.8%)
build/scripts/edit-site/index.min.js	335 kB	+1.31 kB (+0.39%)

_{compressed-size-action}

[ciampo]

@retrofox let's coordinate before jumping into implementation:

• Design System: Add a dedicated Navigation component #79154 explicitly mentions basing the component off base UI's NavigationMenu, and having the primitive live in the @wordpress/ui package;
• that issue also mentions the need for design specs;
• the component will also benefit from the Menu component being finalized and merged first (Menu: Add UI component #79560)
• in general, we should probably agree on a more defined set of specs, before implementing.

cc @WordPress/gutenberg-components

[retrofox]

@retrofox let's coordinate before jumping into implementation:

• Design System: Add a dedicated Navigation component #79154 explicitly mentions basing the component off base UI's NavigationMenu, and having the primitive live in the @wordpress/ui package;
• that issue also mentions the need for design specs;
• the component will also benefit from the Menu component being finalized and merged first (Menu: Add UI component #79560)
• in general, we should probably agree on a more defined set of specs, before implementing.

cc @WordPress/gutenberg-components

Moving PR to draft.

[aduth]

I think we could find a path forward here for some incremental improvements to avoid the current situation where consumers are forced to use tabs even when not appropriate to do so.

The broader ambition for navigation support for Page involves several related dependent navigation components and an expansive API to cover submenus and other aspects explored in #77628 and #76709. This is going to take a lot of work.

But, if we adopt a configuration-based API for specifying navigation, as considered in #76709 (comment), I think we could implement a subset of supports with a simple internal component implementation as a short-term solution.

Based on what's implemented here, if we can keep this to (1) label, (2) URL, and (3) selected state, that should be both relatively simple to implement and mostly future-compatible to the more expansive NavigationMenu component (#79154).

With this, I'd expect:

• The navigation menu component itself is not publicly exported, and is only configurable from the top-level <Page /> component via a navigation prop
• The navigation is decoupled from @wordpress/route, for the same reasons as described in Admin UI: Decouple Page component from @wordpress/route #77040 (i.e. no using @wordpress/route Link directly in the package)

As far as what the API looks like, I think you already have most of it with what you proposed with the Navigation component, but instead surfacing items to the Page component:

<Page
  navigation={ [
    { label: 'Overview', href: '/overview', selected: true },
    { label: 'Products', href: '/products' },
  ] }
/>

A couple differences:

• I suggest using href instead of to for alignment with the Link component, and to avoid implying router coupling that we're moving away from via Admin UI: Decouple Page component from @wordpress/route #77040
• Using selected instead of active to avoid ambiguity with the :active pseudo-class (h/t @ciampo )

[ciampo]

Potentially, rather than a selected property accepted in each navigation item, there could be a separate selected prop that takes the selected href — it would allow for the navigation object to be mostly stable across re-renders.

[retrofox]

Thanks, @aduth. This direction works well for us, and we'll adopt it.

Quick summary of what we'll implement, plus two questions:

• Configuration-based navigation on <Page>, with the navigation component internal (not exported).
• Items limited to label + URL + selected state, decoupled from @wordpress/route (plain anchors by default).
• href (not to) and selected (not active), per your and @ciampo's notes.

Two things to confirm:

1. Shape of the prop.

Since selected only makes sense alongside the items, would you prefer bundling them into a single object rather than two top-level props? Building on @ciampo's point about keeping the items list stable across renders:

<Page
  navigation={ {
    items: [ { label: 'Overview', href: '/overview' }, … ],
    selected: '/overview',
  } }
/>

This keeps Page's top-level API focused (no loose selected prop) and leaves room for future navigation config (e.g. an accessible label) without adding new Page props.

Happy to go with the flat navigation={ [ … ] } + separate selected if you'd rather.

2. Client-side navigation.

With plain anchors, in-app navigation triggers a full reload.

To preserve client-side routing without coupling the package to @wordpress/route, should this include the minimal link injection from #77040 (e.g., components={ { link } }, defaulting to <a>, with @wordpress/boot providing the router Link), or should that land with #77040 and this PR ship plain anchors for now?

[github-actions]

Flaky tests detected in fe1b0a7.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29410438933
📝 Reported issues:

• [Flaky Test] Should navigate inner blocks with arrow keys #39607 in /test/e2e/specs/editor/various/writing-flow.spec.js

[louwie17]

Thanks for moving this forward @retrofox, and I like the middle ground of having a navigation config first. I just left some small comments, but otherwise happy where this is going!

Keyboard focus moves through the links with a visible focus ring.

I don't see any focus ring when using my keyboard. Seems like the Link component does not provide this.

[louwie17]

Do we want to limit this to a single item, in the case where multiple items with the same href are added? Or do we not care about this and expect them to be unique?

[aduth]

Do we want to limit this to a single item, in the case where multiple items with the same href are added? Or do we not care about this and expect them to be unique?

I think it's a good point on both accounts; that we should neither want duplicate aria-current="page" but that it's also reasonable to expect that someone should pass unique values. I'm not sure it's worth the added complexity to try to preempt.

If we were, then maybe it could be done as part of the same validation happening above for non-empty href, to make sure that each href is distinct.

[retrofox]

We enforce uniqueness now: the dev-only validation throws on a duplicate href, right next to the missing-href check, the spot you pointed out for it.

@ciampo asked for the same guard in a separate thread. Regarding the added complexity: it's a few development-only lines, production pays nothing, and it guarantees a single aria-current="page".

[retrofox]

Keyboard focus moves through the links with a visible focus ring.

I don't see any focus ring when using my keyboard. Seems like the Link component does not provide this.

Don't you?

[aduth]

I pushed a few changes I noticed while going through review.

Of note:

• Storybook link capture wasn't working for me in testing, which should be fixed now in 3c7066e.
• Added regression test coverage for scenarios which were flagged in earlier reviews and improved.
• Updated the styling to appear a bit more how I'd expect from the original specs in #76709. I don't know that we ever concretely landed on the visual style here, and in particular around whether to use an underline for the active item. This was noted in the original pull request description and in @ciampo 's initial tech spec in #79154 (comment), and I can see the intent in not wanting to confuse the semantics of links and tabs. We may find ourselves iterating on this design though.

Visual comparison before and after touch-ups in 88b5f92, largely around removing excess space, particularly default header padding when the navigation is present:

Before	After

Otherwise this looks good to me as a first iteration 👍 @louwie17 had submitted a blocking review and I also note that his status is "Busy" and that he may be away, so my inclination is to dismiss the review and address any follow-up comments in subsequent iterations.

[aduth]

Depending on the urgency of this change, it could otherwise make sense to wait direclty for NavigationMenu to be available ?

Do you expect that the component would change the API surface of these changes, which would be something that might be worth settling, and otherwise non-blocking. Regarding urgency, I'll defer to @retrofox , but I am aware of several instances where consumers have been resorting to inappropriate Tabs usage over the lack of a navigation menu support.

[ciampo]

There may be some API changes, but it's early to say. At the same time, I expect that applying the specs proposed in #77628 will result in breaking changes anyway, so maybe there's no point in waiting?

Requested changes have been addressed, and a colleague has mentioned that he will be unavailable to review for an extended time.

[aduth]

At the same time, I expect that applying the specs proposed in #77628 will result in breaking changes anyway, so maybe there's no point in waiting?

That's my instinct as well. For example, there's already some inconsistencies being introduced here (for the better) around link customization, where Page's breadcrumb still hard-codes @wordpress/route Links and here we use components.link customization (related issue: #77040). I think as long as this puts us further toward what we think the API should look like, it's a step in the right direction, and we'll need to make some breaking changes at some point regardless.

[ciampo]

Question (cc @aduth ): should components.link be on Page instead, for a higher-level API, more on the line of the bigger refactor proposed?

[aduth]

Likely yes, and in fact my initial proposal in #77040 included exactly that ("<Page components={ { link: Link } } />").

[aduth]

I've updated this in 4cfaf48 so that components is a top-level prop of Page. This switches back to the linkComponent semantics for Navigation itself, but since it's a private component it shouldn't matter much and I think we won't need as much of the 'bucket' approach for the sub-components where it's more clear and precise what we'll want to control.

[ciampo]

With AnchorHTMLAttributes< HTMLAnchorElement >, the href prop/attribute is optional, but NavigationItem always requires it. This will also cause TS errors later, if we need to write adapters (ie for the wordpress/route link) such as:

type RouteLinkProps = {
	href: string;
	children: React.ReactNode;
	className?: string;
};

const RouteLink = ( { href, ...props }: RouteLinkProps ) => (
	<Link to={ href } { ...props } />
);

The current test and story hide this problem by typing their fake anchor with the same optional-href AnchorHTMLAttributes type. We should probably mark href on link's props as required, update stories and tests

[aduth]

With AnchorHTMLAttributes< HTMLAnchorElement >, the href prop/attribute is optional, but NavigationItem always requires it.

This is a good catch, and it was a little tricky to navigate, between how exactly to make it required (e.g. Pick-ing the props we're actually passing vs. Omit-ing and & intersecting with the override) as well as semantics around render in the underlying Link component. The end result is 38ffb1f:

• Opted for Omit-and-&-intersect, since we had already documented through props "It receives standard anchor attributes [...] them to the element it renders"
• Passing href on the render element (both default and overridden) because otherwise the typings would assume that what's passed to LinkComponent could have omit href because the underlying Link primitive builds its prop types based on anchor props

[ciampo]

I believe Page.navigation is still typed as the complete internal NavigationProps, so TypeScript advertises navigation.linkComponent and navigation.className as supported public configuration?

Header then spreads the object and unconditionally overwrites both values. A consumer can therefore pass valid-looking props that silently do nothing. This also leaves a second apparent link-customization path after the supported one moved to Page.components.link.

I guess one approach here is to split this into a public data-only config (items, currentHref, ariaLabel) and internal renderer props (linkComponent, className), and type Page.navigation with only the public config? That preserves the minimal configuration API discussed in #76709/#77628 and prevents internal markup concerns from becoming part of the Page contract.

[aduth]

I believe Page.navigation is still typed as the complete internal NavigationProps, so TypeScript advertises navigation.linkComponent and navigation.className as supported public configuration?

Good call 👍 I split the internal and public-facing types in 6937f88.

[ciampo]

This type would allow something like

<Page components={{ link: 'span' }}>

The public override does not need to accept intrinsic strings because the native <a> is already the default. What about using ComponentType<NavigationLinkProps> instead? Internally, Navigation can use linkComponent ?? 'a'.

[aduth]

Hm, right, I had done this intentionally in 4259798 as a way to line up the typings so that linkComponent could destructure, but it sounds like the previous approach is probably better to avoid exposing other element tag names as invalid. I'll just revert.

[aduth]

Reverted the ElementType typings in 085c839.

[ciampo]

It looks like the router adapter can create two current links for nested URLs.

For example, at /products/settings:

• TanStack Router (which powers @wordpress/route) also marks /products as active by default
• Page marks /products/settings from currentHref
• Both links then get aria-current="page" and the current-item styling.

We should make sure that the @wordpress/route adapter uses activeOptions={{ exact: true }} (and document it).

Ideally, we should also test the real adapter with nested URLs and assert that only one link is current.

[aduth]

Hmm, I'm not really sure how to proceed here. TanStack Router is going to apply aria-current to nested links regardless of what we do here. If that's a problem, then we need to solve that at the root, or it's something that any consumer for @wordpress/route will need to think about. I guess I don't really see this as a Page problem. Sure, we add aria-current and that overlaps with what Tanstack is doing, but even if we didn't do that, the problem you describe still exists.

I was initially going to add a test here, but I feel like this is such a concern of the integration itself that it's more appropriate to belong where the integration itself happens. And with #77040, I'd like to move away from @wordpress/admin-ui being entangled with the router.

Where are you suggesting that this documentation should live?

[ciampo]

Maybe we can start with a Storybook example where we show how to work around it, as of today.

But I agree that this is something to be solved separately

[ciampo]

All my feedback is addressed 🚀

One minor nit: the PR description still shows an old code snippet where the custom components are nested under navigation.components.

But otherwise, no additional feedback on my end!

[aduth]

Thanks @retrofox for all the work here, and @ciampo @louwie17 for all the feedback. It'll be good to see this land so that consumers won't need to resort to using tabs inappropriately for navigation!