feat(ui): replace Header tabs with nav-based grouped navigation#33527
Merged
feat(ui): replace Header tabs with nav-based grouped navigation#33527
Conversation
Contributor
|
Important This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior. Changed Packages
|
backstage-goalie
Bot
added
size:large
Contributor
🎨 Visual Testing with Chromatic
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates @backstage/ui’s Header navigation to use a semantic <nav> with flat links and optional grouped dropdown menus, moving active state control to a new activeTabId prop and introducing new internal nav components/styles to support indicators and grouping.
Changes:
- Replace
Header’sTabs/TabList/Tabrendering with a newHeaderNavimplementation (links + dropdown groups). - Introduce new
HeaderNavTabItemunion types (flat vs group) plusactiveTabIdto control highlighted state. - Update public API exports, docs, and changeset/migration notes for the breaking
tabsprop change.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/ui/src/components/Header/types.ts | Introduces new nav tab/group types + activeTabId prop; adds isTabGroup guard. |
| packages/ui/src/components/Header/index.tsx | Exports new Header nav definitions/types and isTabGroup. |
| packages/ui/src/components/Header/definition.ts | Adds activeTabId to component definition propDefs. |
| packages/ui/src/components/Header/HeaderNav.tsx | New <nav> renderer for flat and grouped header navigation items. |
| packages/ui/src/components/Header/HeaderNavIndicators.tsx | New indicator positioning logic via CSS custom properties. |
| packages/ui/src/components/Header/HeaderNavDefinition.ts | New defineComponent definitions for nav root/item/group. |
| packages/ui/src/components/Header/HeaderNav.module.css | New styles for nav layout plus active/hover indicators. |
| packages/ui/src/components/Header/Header.tsx | Switches Header from Tabs to the new HeaderNav. |
| packages/ui/src/components/Header/Header.stories.tsx | Updates Storybook stories to drive activeTabId and demonstrate grouped tabs. |
| packages/ui/report.api.md | Updates API report for new exported types/definitions and prop changes. |
| docs-ui/src/app/components/header/props-definition.tsx | Updates docs prop definitions for new tabs type and adds activeTabId. |
| .changeset/chatty-cups-create.md | Adds breaking-change changeset with migration instructions. |
Naycon
force-pushed
the
bui-header-grouped-navigation
branch
from
f72287f to
7897f29
Compare
Naycon
force-pushed
the
bui-header-grouped-navigation
branch
from
7897f29 to
7859f15
Compare
Naycon
force-pushed
the
bui-header-grouped-navigation
branch
2 times, most recently
from
32f2670 to
d010b73
Compare
Replace the RA Tabs/TabList/Tab rendering in the Header component with a nav-based approach that supports grouped dropdown items via BUI Menu. Active state is consumer-controlled via a new activeTabId prop. The indicator system follows the TabsIndicators CSS custom property pattern for animated active/hover/focus states. Signed-off-by: Johan Persson <johanopersson@gmail.com>
Signed-off-by: Johan Persson <johanopersson@gmail.com>
Naycon
force-pushed
the
bui-header-grouped-navigation
branch
from
d010b73 to
a13c5ae
Compare
cdedreuille
approved these changes
Mar 24, 2026
Collaborator
cdedreuille
left a comment
cdedreuille
left a comment
There was a problem hiding this comment.
Great workaround on this one 🙏
Contributor
|
Thank you for contributing to Backstage! The changes in this pull request will be part of the |
backstage-goalie
Bot
added
waiting-for:merge
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Hey, I just made a Pull Request!
Replaces the RA
Tabs/TabList/Tabrendering in theHeadercomponent with a<nav>-based approach. Flat items render as links viauseLink, grouped items render as BUIMenuTrigger/Menu/MenuItemdropdowns. Active state is consumer-controlled via a newactiveTabIdprop.Breaking change: The
tabsprop type changes fromHeaderTab[]toHeaderNavTabItem[]. See the changeset for migration details.New files:
HeaderNav.tsx— internal nav component (flat links + group menus)HeaderNavIndicators.tsx— animated active/hover/focus indicatorHeaderNavDefinition.ts—defineComponentdefinitionsHeaderNav.module.css— stylesScreenshots
✔️ Checklist
Signed-off-byline in the message.