Add Top Bar Navigation component

[andrewHEguardian]

What does this change?

Adds the Top Bar Navigation component

Figma

TopBarNavigation

The Top Bar Navigation component is a link to another part of a tool, and also shows the currently navigated page or section.

When to use

• In a Top Bar component
• When you have multiple pages or tabs in an app and need a way to navigate between them

Peer dependencies

• @emotion/react
• react
• react-dom
• typescript
• ToDo: react aria if menu?

See the peerDependencies section of package.json for compatible versions.

See custom component build for usage without React/Emotion.

Example usage

import { TopBarNavigation } from '@guardian/stand/TopBar';

/* types, if required */
import type {
	TopBarNavigationProps,
	TopBarNavigationTheme,
} from '@guardian/stand/TopBar';

export const Component = () => (
	<TopBarNavigation text="Recipe" icon="yakitori" />
);

Props

Name	Type	Required	Default	Description
text	string	Yes	N/A	Text content to render inside the component.
size	'md' | 'sm'	No	'md'	Size of the component - affects text and icon.
isSelected	boolean	No	false	Whether this navigation component represents the currently selected navigation option.
icon	IconProps['symbol'] | Exclude<IconProps['children'], string>	No	N/A	Icon rendered inside the navigation. Accepts a MaterialSymbol name or a non-string ReactNode (e.g. an SVG element). Size is default.
menuChildren	ReactNode	No	false	Menu sections and items to render in the dropdown menu - only children of type MenuSection and MenuItem will be rendered. href and onPress will be ignored if this prop is supplied.
href	string	No	N/A	A URL to link to handle navigation.
onPress	(e: PressEvent) => void	No	N/A	On Press handler that handles navigation.
theme	TopBarNavigationTheme	No	N/A	Custom theme overrides.
cssOverrides	SerializedStyles	No	N/A	Custom CSS styles.
className	string	No	N/A	Additional class name(s).

Customisation

We recommend using the TopBarNavigation component as provided, but it can be customised using the theme or cssOverrides props as required.

Custom theme

The theme prop allows you to override specific design tokens for the TopBarNavigation component:

import type { TopBarNavigationTheme } from '@guardian/stand/TopBar';
import { TopBarNavigation } from '@guardian/stand/TopBar';
import { baseColors } from '@guardian/stand';

const customTheme: Partial<TopBarNavigationTheme> = {
	selected: {
		color: baseColors.blue[200],
		'border-bottom': `5px solid ${baseColors['cool-purple'][700]}`,
	},
};

const Component = () => (
	<TopBarNavigation
		theme={customTheme}
		icon="file_upload"
		text="Navigation"
		isSelected={true}
	/>
);

CSS overrides

The cssOverrides prop allows you to pass custom CSS to the TopBarNavigation component:

import { TopBarNavigation } from '@guardian/stand/TopBar';
import { semanticColors } from '@guardian/stand';
import { css } from '@emotion/react';

const customStyles = css\`
	background-color: ${semanticColors.surface['dark-1']};
	color: ${semanticColors.text['inverse-default']};
\`;

const Component = () => (
	<TopBarNavigation
		cssOverrides={customStyles}
		icon="file_upload"
		text="Navigation"
		isSelected={true}
	/>
);

Custom Component Build

If you're not using React/Emotion, you can create a custom TopBarNavigation component using the styles defined in the TopBarNavigationTheme type.

TypeScript/JavaScript

Use the componentTopBarNavigation variable and the ComponentTopBarNavigation type:

How has this change been tested?

Storybook and Sandbox

Images

Accessibility

• Tested with screen reader
• Navigable with keyboard
• Colour contrast passed
• The change doesn't use only colour to convey meaning

[github-actions]

Note

The following canaries were published to NPM:

• @guardian/stand@0.0.0-canary-20260306125736

🐥

[github-actions]

Dependency Compatibility Matrix

React	Emotion	TypeScript	RAC	Typecheck	Unit	E2E	Build	Overall
17	11.11.4	~5.0	1.13.0	ok	ok	ok	ok	✅
17	11.11.4	~5.0	1.16.0	ok	ok	ok	ok	✅
17	11.11.4	~5.1	1.13.0	ok	ok	ok	ok	✅
17	11.11.4	~5.1	1.16.0	ok	ok	ok	ok	✅
17	11.11.4	~5.9	1.13.0	ok	ok	ok	ok	✅
17	11.11.4	~5.9	1.16.0	ok	ok	ok	ok	✅
17	11.14.0	~5.0	1.13.0	ok	ok	ok	ok	✅
17	11.14.0	~5.0	1.16.0	ok	ok	ok	ok	✅
17	11.14.0	~5.1	1.13.0	ok	ok	ok	ok	✅
17	11.14.0	~5.1	1.16.0	ok	ok	ok	ok	✅
17	11.14.0	~5.9	1.13.0	ok	ok	ok	ok	✅
17	11.14.0	~5.9	1.16.0	ok	ok	ok	ok	✅
18	11.11.4	~5.0	1.13.0	ok	ok	ok	ok	✅
18	11.11.4	~5.0	1.16.0	ok	ok	ok	ok	✅
18	11.11.4	~5.1	1.13.0	ok	ok	ok	ok	✅
18	11.11.4	~5.1	1.16.0	ok	ok	ok	ok	✅
18	11.11.4	~5.9	1.13.0	ok	ok	ok	ok	✅
18	11.11.4	~5.9	1.16.0	ok	ok	ok	ok	✅
18	11.14.0	~5.0	1.13.0	ok	ok	ok	ok	✅
18	11.14.0	~5.0	1.16.0	ok	ok	ok	ok	✅
18	11.14.0	~5.1	1.13.0	ok	ok	ok	ok	✅
18	11.14.0	~5.1	1.16.0	ok	ok	ok	ok	✅
18	11.14.0	~5.9	1.13.0	ok	ok	ok	ok	✅
18	11.14.0	~5.9	1.16.0	ok	ok	ok	ok	✅
19	11.14.0	~5.0	1.13.0	ok	ok	ok	ok	✅
19	11.14.0	~5.0	1.16.0	ok	ok	ok	ok	✅
19	11.14.0	~5.1	1.13.0	ok	ok	ok	ok	✅
19	11.14.0	~5.1	1.16.0	ok	ok	ok	ok	✅
19	11.14.0	~5.9	1.13.0	ok	ok	ok	ok	✅
19	11.14.0	~5.9	1.16.0	ok	ok	ok	ok	✅

Columns show granular outcomes for each dependency set: ok = passed, fail = failed, skip = upstream failure prevented running later stages. Overall: ✅ all passed, ⚠️ only skips (no hard fails), ❌ at least one fail.
Last updated: 2026-03-13T08:55:09.718Z (commit 5821848)

[github-actions]

Note

The following canaries were published to NPM:

• @guardian/stand@0.0.0-canary-20260311122850

🐥

[andrewHEguardian]

Attempting to kick off Chromatic...