PluginHeader

A plugin header with icon, title, custom actions, and navigation tabs.

import { PluginHeader } from '@backstage/ui';

<PluginHeader title="My plugin" />

API reference#

Prop	Type	Default	Description
icon	ReactNode	-	Icon displayed before the title.
title	string	-	Main heading text for the header.
titleLink	string	-	URL the title links to when clicked.
customActions	ReactNode	-	Custom elements rendered in the toolbar area.
tabs		-	Navigation tabs displayed below the toolbar.
onTabSelectionChange	(key: Key) => void	-	Handler called when the selected tab changes.
className	string	-	Additional CSS class name for custom styling.

Examples#

Simple plugin header#

My plugin

<PluginHeader
  title="My plugin"
  titleLink="/"
  customActions={
    <>
      <ButtonIcon variant="tertiary" icon={<RiCloudy2Line />} />
      <ButtonIcon variant="tertiary" icon={<RiEmotionHappyLine />} />
      <ButtonIcon variant="tertiary" icon={<RiHeartLine />} />
    </>
  }
/>

Plugin header with tabs#

Tabs use React Router and highlight automatically based on the current route.

My plugin

Overview Checks Tracks Campaigns Integrations

<PluginHeader
  title="My plugin"
  titleLink="/"
  tabs={[
    { id: 'overview', label: 'Overview', href: '/overview' },
    { id: 'checks', label: 'Checks', href: '/checks' },
    { id: 'tracks', label: 'Tracks', href: '/tracks' },
    { id: 'campaigns', label: 'Campaigns', href: '/campaigns' },
    { id: 'integrations', label: 'Integrations', href: '/integrations' },
  ]}
/>

Plugin header with Header#

Combine with Header for multi-level navigation.

My plugin

Overview Checks

Page title

<PluginHeader
  title="My plugin"
  titleLink="/"
  tabs={[
    { id: 'overview', label: 'Overview', href: '/overview' },
    { id: 'checks', label: 'Checks', href: '/checks' },
  ]}
/>
<Header
  title="Page title"
  tabs={[
    { id: 'banana', label: 'Banana', href: '/banana' },
    { id: 'apple', label: 'Apple', href: '/apple' },
  ]}
  customActions={<Button>Custom action</Button>}
/>

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-PluginHeader
bui-PluginHeaderToolbar
bui-PluginHeaderToolbarContent
bui-PluginHeaderToolbarControls
bui-PluginHeaderToolbarIcon
bui-PluginHeaderToolbarName
bui-PluginHeaderTabsWrapper

Changelog#

Version 0.13.0#

Changes

Migrated all components from useStyles to useDefinition hook. Exported OwnProps types for each component, enabling better type composition for consumers. #33050
Fixed PluginHeader to avoid triggering ResizeObserver loop completed with undelivered notifications warnings when used in layouts that react to the header height, such as pages that use FullPage. #33368
Fixed tab matchStrategy matching to ignore query parameters and hash fragments in tab href values. Previously, tabs with query params in their href (e.g., /page?group=foo) would never show as active since matching compared the full href string against location.pathname which never includes query params. #33047
Merged the internal PluginHeaderToolbar component into PluginHeader, removing the separate component and its associated types (PluginHeaderToolbarOwnProps, PluginHeaderToolbarProps) and definition (PluginHeaderToolbarDefinition). This is an internal refactor with no changes to the public API of PluginHeader. #33085

Version 0.12.0#

Breaking Changes

Breaking Renamed the Header component to PluginHeader for clarity.

The following exports have been renamed:
- Header → PluginHeader
- HeaderProps → PluginHeaderProps
- HeaderDefinition → PluginHeaderDefinition
The HeaderTab type is unchanged as it is shared with HeaderPage.

CSS class names have been updated from bui-Header* to bui-PluginHeader*. #32875

Migration Guide:
```
-import { Header, HeaderDefinition } from '@backstage/ui';
+import { PluginHeader, PluginHeaderDefinition } from '@backstage/ui';

-<Header title="My plugin" />
+<PluginHeader title="My plugin" />
```

Version 0.9.0#

Breaking Changes

Breaking Changed className prop behavior to augment default styles instead of being ignored or overriding them.

If you were passing custom className values to any of these components that relied on the previous behavior, you may need to adjust your styles to account for the default classes now being applied alongside your custom classes. #31496

Changes

Fix broken external links in Backstage UI PluginHeader component. #31525