Repository navigation
Conversation
🤖 PR meta 🤖🎉 PropsUnlinked AccountsThe following contributors have not linked their GitHub and WordPress.org accounts: @MrSuddenJoy. Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases. If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. Props Bot commandsYou can trigger Props Bot actions by commenting on this PR:
Updated as activity occurs, without notifying anyone named here. Add the 📦 Bundle sizeSize Change: -8.06 kB (-0.09%) Total Size: 8.66 MB 📦 View Changed
⚡ PerformanceShow the resultsClient side metrics exclude the server response time. front-end-block-theme
front-end-classic-theme
media-processing
media-upload
post-editor
site-editor
🏁 Flaky testsSome 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. Navigates the list via UP/DOWN arrow keys from action buttons in
|
There was a problem hiding this comment.
🟡 Changes recommended
Removing the Breadcrumbs export breaks a Storybook module that still imports it and passes the component to Page; its import and breadcrumbs prop must be migrated to the array configuration.
1 open issue
What changed in this PR
This PR makes Page breadcrumbs configuration-based and removes @wordpress/admin-ui’s routing dependency, addressing #77040 and following the existing navigation API pattern.
Changes:
- Replace the public
Breadcrumbscomponent with aPage.breadcrumbsarray and configurable link rendering. - Apply
headingLevelto breadcrumb headings and derive the page region’s accessible name from the last breadcrumb when appropriate. - Migrate route consumers, update tests and stories, and document the breaking API change.
| File | Description |
|---|---|
| routes/site-health/stage.tsx | Migrate breadcrumbs and supply router links. |
| routes/navigation-edit/stage.tsx | Adopt breadcrumb configuration and router links. |
| routes/media-editor/stage.tsx | Migrate standalone and routed breadcrumb configurations. |
| routes/dashboard/stage.tsx | Use a single-item breadcrumb array. |
| packages/admin-ui/tsconfig.json | Remove the route project reference. |
| packages/admin-ui/tsconfig.build.json | Remove the build-time route reference. |
| packages/admin-ui/src/stories/with-router.tsx | Delete the router decorator. |
| packages/admin-ui/src/page/types.ts | Document custom links for breadcrumbs. |
| packages/admin-ui/src/page/test/index.jsdom.test.tsx | Cover breadcrumb naming, headings, and custom links. |
| packages/admin-ui/src/page/stories/index.story.tsx | Convert stories to breadcrumb arrays. |
| packages/admin-ui/src/page/index.tsx | Accept breadcrumb configuration and derive region names. |
| packages/admin-ui/src/page/header.tsx | Render internal breadcrumbs with page settings. |
| packages/admin-ui/src/index.ts | Remove the public Breadcrumbs export. |
| packages/admin-ui/src/breadcrumbs/types.ts | Define URL-based items and rendering options. |
| packages/admin-ui/src/breadcrumbs/test/index.jsdom.test.tsx | Update tests for the internal breadcrumb contract. |
| packages/admin-ui/src/breadcrumbs/stories/index.story.tsx | Remove standalone Breadcrumbs stories. |
| packages/admin-ui/src/breadcrumbs/index.tsx | Support custom links and configurable heading levels. |
| packages/admin-ui/README.md | Remove documentation for the retired export. |
| packages/admin-ui/package.json | Remove the routing dependency. |
| packages/admin-ui/CHANGELOG.md | Document the breaking change and migration. |
| package-lock.json | Synchronize the dependency removal. |
Review effort: Balanced
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
|
Seems unrelated but in my testing the admin bar disappears in the Extensible Site Editor 🤔 |
Likely this one? #86992 |
|
FYI I've been testing this with Jetpack which uses breadcrumbs quite heavily so good test bench: Automattic/jetpack@trunk...simison/admin-ui-breadcrumbs-api-d186f2 One finding so far is that they're doing some style overrides in couple places for truncation to work well, which might either indicate bugs in our component or some misuse. Didn't look closer yet. (Related issue #77391) |
Thanks for doing this downstream testing 🙏 Since we don't currently have usage to validate against in Gutenberg itself, a lot of this is speculative in terms of what breadcrumbs behavior we should expect to provide, but the downstream validation is a primary source of understanding whether it's sufficient. |
ciampo
left a comment
There was a problem hiding this comment.
Deleting the Storybook router decorator leaves its ESLint suppression behind. Could you run npm run lint:js:prune-suppressions and include the resulting deletion?
|
|
||
| ### Breaking Changes | ||
|
|
||
| - `Page`: The `breadcrumbs` prop now takes an array of `{ label, href }` items in place of a `Breadcrumbs` element. Links render through `components.link`, like `navigation`, so pass your router's link component there. The page region takes its name from the last item when it has no `ariaLabel` or string `title`. The `Breadcrumbs` component is no longer exported, and the package no longer depends on `@wordpress/route`. |
| breadcrumbs={ [ | ||
| { | ||
| label: 'Root breadcrumb', | ||
| href: '/connectors', |
There was a problem hiding this comment.
Clicking “Root breadcrumb” now takes the preview to /connectors on the Storybook host. Could we use a fragment like the other Page stories and remove the unused withRouter decorator?
| if ( process.env.NODE_ENV !== 'production' ) { | ||
| const invalidItem = precedingItems.find( ( item ) => ! item.to ); | ||
| const invalidItem = precedingItems.find( | ||
| ( item ) => typeof item.href !== 'string' |
There was a problem hiding this comment.
An ancestor with href: '' now passes validation and links back to the current page. Could we reject blank destinations here and cover that case alongside the missing-href test?

What?
Closes #77040
Updates
@wordpress/admin-uito removeBreadcrumbsfrom its public API, instead receivingbreadcrumbson thePagecomponent as an array configuration.In doing so, it also addresses several bug fixes and improvements:
headingLevelpassed toPagedoesn't actually control the heading level of a breadcrumb heading, which is always an h1.ariaLabelthat duplicates the breadcrumbs (example).@wordpress/route, thus closing Admin UI: Decouple Page component from@wordpress/route#77040.Why?
This was always the intention, and ties together several pieces around API design of configuration props in #76709 (comment), and decoupling Page from routing in #77040.
For parity, it follows the pattern established in #79746, which did the same thing effectively for
navigation, accepting it as a configuration object rather than an element.How?
The
breadcrumbsprop now takes an array of{ label, href }items in place of aBreadcrumbselement. This is a breaking change. The package is a bundled package so this is expected to be published as a new major version.Testing Instructions
Test affected routes (e.g. Site Health, Extensible Site Editor Navigation editing, Media editor, etc.) and ensure there are no regressions with the appearance and functionality of the breadcrumbs.
Use of AI Tools
Researched and implemented in coordination with Claude Code + Opus 5.5.