feat(ui): add automatic active tab detection to Header by Naycon · Pull Request #33783 · backstage/backstage

Naycon · 2026-04-07T09:02:23Z

Hey, I just made a Pull Request!

When activeTabId is omitted, HeaderNav now auto-detects the active
tab from the current route using matchRoutes. This eliminates the
boilerplate useActiveTabId pattern that every consumer had to
reimplement.

The activeTabId prop accepts three states:

undefined (omitted) — auto-detect from current route
string — explicit tab ID (existing behavior, unchanged)
null — explicitly no active tab

Also refactors HeaderNavLink to properly use the definition system
(resolveHref, analytics) and resolves relative tab hrefs correctly.

✔️ Checklist

A changeset describing the change and affected packages.
Added or updated documentation
Tests for new functionality and regression tests for bug fixes
Screenshots attached (for UI changes)
All your commits have a Signed-off-by line in the message.

Signed-off-by: Johan Persson <johanopersson@gmail.com>

…licit activeTabId Signed-off-by: Johan Persson <johanopersson@gmail.com>

… recipe Signed-off-by: Johan Persson <johanopersson@gmail.com>

Signed-off-by: Johan Persson <johanopersson@gmail.com>

Add resolveHref to HeaderNavItemDefinition so tab links with relative hrefs are resolved against the router context before rendering. Signed-off-by: Johan Persson <johanopersson@gmail.com>

backstage-goalie · 2026-04-07T09:02:53Z

Important

This PR includes changes that affect public-facing API. Please ensure you are adding/updating documentation for new features or behavior.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage/ui	packages/ui	minor	`v0.14.0-next.1`

github-actions · 2026-04-07T09:07:21Z

🎨 Visual Testing with Chromatic

No visual changes detected - View build in Chromatic
453 stories for 51 Components - Preview changes in Storybook

Copilot

Pull request overview

This PR updates HeaderNav to support automatic active-tab detection from the current React Router location when activeTabId is omitted, while also allowing null to explicitly opt out of an active tab. It also aligns HeaderNavLink with the definition system for href resolution and analytics.

Changes:

Add router-based active tab auto-detection when activeTabId is undefined (omitted) and a Router is present.
Expand activeTabId to support string | null, where null means “no active tab”.
Refactor HeaderNavLink to use the definition system (resolveHref, analytics) and update stories/docs accordingly.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/ui/src/components/Header/HeaderNav.tsx	Adds auto-detection via `matchRoutes`, refactors link rendering to use definition-based href resolution and analytics.
packages/ui/src/components/Header/types.ts	Updates `activeTabId` type to `string \| null` and introduces internal `HeaderNavLinkProps`.
packages/ui/src/components/Header/HeaderNavDefinition.ts	Moves analytics + `resolveHref` to the item definition and expands item prop defs.
packages/ui/src/components/Header/Header.stories.tsx	Simplifies stories to rely on auto-detection; adds explicit active tab story.
packages/ui/src/recipes/PluginHeaderAndHeader.stories.tsx	Removes local active-tab hook and configures router entries to demonstrate auto-detection.
docs-ui/src/app/components/header/page.mdx	Updates docs text to describe the new `activeTabId` behavior.
docs-ui/src/app/components/header/props-definition.tsx	Updates prop documentation to reflect `null` and omission semantics.
docs-ui/src/app/components/header/components.tsx	Sets `MemoryRouter` initial entries so examples render with a deterministic active tab.
packages/ui/report.api.md	Updates extracted API report to reflect definition/type changes.
.changeset/cold-ways-double.md	Adds a changeset documenting the behavior change.

Rugvip · 2026-04-07T09:33:20Z

    readonly root: 'bui-HeaderNavItem';
  };
+  readonly analytics: true;
+  readonly resolveHref: true;


Is setting this a breaking change?

Hmm, maybe it depends on how you reason about it? 🤔 It's breaking in that it changes the behavior, but the previous behavior was broken and not following any reasonable patterns. But yes, can mark it as a breaking change just in case someone relied on it.

I was thinking more generally actually, what is the impact on behavior from setting or clearing this, should we consider both to be breaking, neither, or just one direction? Not blocking this PR btw, just realized it's something that's useful to settle

Signed-off-by: Johan Persson <johanopersson@gmail.com>

Copilot

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

github-actions · 2026-04-07T15:26:35Z

Thank you for contributing to Backstage! The changes in this pull request will be part of the 1.50.0 release, scheduled for Tue, 14 Apr 2026.

Naycon added 7 commits March 31, 2026 15:09

feat(ui): widen activeTabId type to accept null

d5bffab

Signed-off-by: Johan Persson <johanopersson@gmail.com>

feat(ui): add automatic active tab detection to HeaderNav

21a3b70

Signed-off-by: Johan Persson <johanopersson@gmail.com>

feat(ui): update Header stories to demonstrate auto-detection and exp…

c3c32c6

…licit activeTabId Signed-off-by: Johan Persson <johanopersson@gmail.com>

refactor(ui): remove manual useActiveTabId from PluginHeaderAndHeader…

b074067

… recipe Signed-off-by: Johan Persson <johanopersson@gmail.com>

docs(ui): update Header docs for activeTabId auto-detection

1c77677

Signed-off-by: Johan Persson <johanopersson@gmail.com>

chore(ui): add API report and changeset for activeTabId auto-detection

66bc388

Signed-off-by: Johan Persson <johanopersson@gmail.com>

fix(ui): resolve relative hrefs in HeaderNav tabs

b2344ea

Add resolveHref to HeaderNavItemDefinition so tab links with relative hrefs are resolved against the router context before rendering. Signed-off-by: Johan Persson <johanopersson@gmail.com>

Naycon requested a review from a team as a code owner April 7, 2026 09:02

Copilot AI review requested due to automatic review settings April 7, 2026 09:02

backstage-goalie Bot added size:medium Medium-sized pull requests receive no change in priority for reviews. waiting-for:review The PR needs a review and will be visible in the review queue unless already assigned an owner. labels Apr 7, 2026

Copilot started reviewing on behalf of Naycon April 7, 2026 09:03 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Comment thread packages/ui/src/components/Header/HeaderNav.tsx

Rugvip approved these changes Apr 7, 2026

View reviewed changes

backstage-goalie Bot added waiting-for:merge The PR has been approved and is awaiting merge. and removed waiting-for:review The PR needs a review and will be visible in the review queue unless already assigned an owner. labels Apr 7, 2026

chore(ui): add breaking change changeset for HeaderNav resolveHref

7608af5

Signed-off-by: Johan Persson <johanopersson@gmail.com>

Copilot AI review requested due to automatic review settings April 7, 2026 13:11

Naycon force-pushed the bui-header-nav-add-active-tab-matching branch from 1d348ba to 7608af5 Compare April 7, 2026 13:11

Copilot started reviewing on behalf of Naycon April 7, 2026 13:12 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

Comment thread packages/ui/src/components/Header/HeaderNavDefinition.ts

Comment thread docs-ui/src/app/components/header/props-definition.tsx

Naycon merged commit b4a1875 into master Apr 7, 2026
32 checks passed

Naycon deleted the bui-header-nav-add-active-tab-matching branch April 7, 2026 15:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ui): add automatic active tab detection to Header#33783

feat(ui): add automatic active tab detection to Header#33783
Naycon merged 8 commits intomasterfrom
bui-header-nav-add-active-tab-matching

Naycon commented Apr 7, 2026

Uh oh!

backstage-goalie Bot commented Apr 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Rugvip Apr 7, 2026

Uh oh!

Naycon Apr 7, 2026

Uh oh!

Rugvip Apr 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Naycon commented Apr 7, 2026

Hey, I just made a Pull Request!

✔️ Checklist

Uh oh!

backstage-goalie Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changed Packages

Uh oh!

github-actions Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎨 Visual Testing with Chromatic

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Rugvip Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Naycon Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Rugvip Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

backstage-goalie Bot commented Apr 7, 2026 •

edited

Loading

github-actions Bot commented Apr 7, 2026 •

edited

Loading