Top nav items

Buttons and elements for the top nav.

These components can be used within the top nav from layout.

For other components that can be used within the top nav, see navigation resources (Atlassians only), (opens new window).

Start items

These actions go in the top nav start area. They are left-aligned in the following order:

Side nav toggle button: Opens and closes the side nav.
App switcher: Opens and closes an app switcher. See navigation resources (Atlassians only), (opens new window) for recommended platform components.

Use one of the following logo components to orient users and provide a persistent link to the app landing page:

App logo: A container for an app's logo icon and name.
Custom logo: A container for custom logo images.
Custom title: Optional text used for app customisation by customers.

Confluence

import React from 'react';

import { ConfluenceIcon } from '@atlaskit/logo/confluence-icon';
import { SideNavToggleButton } from '@atlaskit/navigation-system/layout/side-nav';
import { TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';
import { AppLogo, AppSwitcher } from '@atlaskit/navigation-system/top-nav-items';

import { MockTopBar } from '../common/mock-top-bar';

export function TopNavStartLayoutExample(): React.JSX.Element {
	return (
		<MockTopBar>
			<TopNavStart
				sideNavToggleButton={
					<SideNavToggleButton
						defaultCollapsed
						collapseLabel="Collapse sidebar"
						expandLabel="Expand sidebar"
					/>
				}
			>
				{' '}
				{null}
				<AppSwitcher label="App switcher" />
				<AppLogo
					href="https://jira.atlassian.com"
					icon={ConfluenceIcon}
					name="Confluence"
					label="Home page"
				/>
			</TopNavStart>
		</MockTopBar>
	);
}

export default TopNavStartLayoutExample;

App switcher

App switcher opens the app switcher menu. By default, it uses the Atlassian app switcher icon.

Use the optional icon prop to replace the default icon with a custom visual, such as a product logo. Continue to provide a meaningful label so the custom visual has an accessible name.

Jira

import React from 'react';

import Avatar from '@atlaskit/avatar/avatar';
import { JiraIcon } from '@atlaskit/logo/jira/icon';
import { TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';
import { AppLogo, AppSwitcher } from '@atlaskit/navigation-system/top-nav-items';

import dstLogo from '../../images/dst.png';
import { MockTopBar } from '../common/mock-top-bar';

const CustomAppSwitcherIcon = () => <Avatar size="small" appearance="square" src={dstLogo} />;

export const CustomAppSwitcherExample = (): React.JSX.Element => {
	return (
		<MockTopBar>
			<TopNavStart sideNavToggleButton={null}>
				<AppSwitcher icon={CustomAppSwitcherIcon} label="App switcher" onClick={() => {}} />
				<AppLogo href="https://jira.atlassian.com" icon={JiraIcon} name="Jira" label="Home page" />
			</TopNavStart>
		</MockTopBar>
	);
};

export default CustomAppSwitcherExample;

Side nav toggle button

The side nav toggle button must be passed to TopNavStart through the sideNavToggleButton prop, not via children.

When the keyboard shortcut is enabled, the toggle button’s tooltip will automatically show Ctrl+[ as the shortcut.
The toggle button appears before the app switcher and logo, whether the side nav is collapsed or expanded.

import React from 'react';

import { SideNavToggleButton } from '@atlaskit/navigation-system/layout/side-nav';
import { TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';

import { MockTopBar } from '../common/mock-top-bar';

export function TopNavStartToggleExample(): React.JSX.Element {
	return (
		<MockTopBar>
			<TopNavStart
				sideNavToggleButton={
					<SideNavToggleButton
						defaultCollapsed
						collapseLabel="Collapse sidebar"
						expandLabel="Expand sidebar"
					/>
				}
			>
				{' '}
				{null}
			</TopNavStart>
		</MockTopBar>
	);
}

export default TopNavStartToggleExample;

App logo

App logo displays an app logo icon and name.

It has a maximum width of 320px, after which the app name truncates.
At s breakpoints and below (less that 1024px), the app name is not shown.

See the responsive section for more information.

Jira

import React from 'react';

import { JiraIcon } from '@atlaskit/logo/jira-icon';
import { TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';
import { AppLogo } from '@atlaskit/navigation-system/top-nav-items';

import { MockTopBar } from '../common/mock-top-bar';

export const AppLogoExample = (): React.JSX.Element => {
	return (
		<MockTopBar>
			<TopNavStart sideNavToggleButton={null}>
				<AppLogo href="https://jira.atlassian.com" icon={JiraIcon} name="Jira" label="Home page" />
			</TopNavStart>
		</MockTopBar>
	);
};

export default AppLogoExample;

Secondary name

Use the optional secondaryName prop to add supporting context below the app name, such as the current experience or workspace. The supporting context is displayed in wider viewports and is hidden with the app name at s breakpoints and below (less than 1024px).

JiraSoftware development

import React from 'react';

import { JiraIcon } from '@atlaskit/logo/jira/icon';
import { TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';
import { AppLogo } from '@atlaskit/navigation-system/top-nav-items';

import { MockTopBar } from '../common/mock-top-bar';

export const AppLogoSecondaryNameExample = (): React.JSX.Element => {
	return (
		<MockTopBar>
			<TopNavStart sideNavToggleButton={null}>
				<AppLogo
					href="https://jira.atlassian.com"
					icon={JiraIcon}
					name="Jira"
					secondaryName="Software development"
					label="Jira home page"
				/>
			</TopNavStart>
		</MockTopBar>
	);
};

export default AppLogoSecondaryNameExample;

Custom logo

Custom logo provides a container for custom logo images with the following constraints:

Maximum width: 320px. If the image is wider than this, the logo will scale down to fit.
Maximum height: 24px. If the image is shorter than this, the logo will scale up to fit.

Do not provide explicit width and height values on the image, otherwise it will not respect the container size.

At s breakpoints and below (less that 1024px), only the provided icon is shown. Above s breakpoints, the provided logo is shown.

See the responsive section for more information.

import React from 'react';

import { TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';
import { CustomLogo } from '@atlaskit/navigation-system/top-nav-items';

import customIconSrc from '../../images/20x20.png';
import customLogoSrc from '../../images/200x20.png';
import { MockTopBar } from '../common/mock-top-bar';

const CustomLogoImage = () => <img src={customLogoSrc} alt="" />;
const CustomIconImage = () => <img src={customIconSrc} alt="" />;

export const CustomLogoExample = (): React.JSX.Element => {
	return (
		<MockTopBar>
			<TopNavStart sideNavToggleButton={null}>
				<CustomLogo
					href="https://jira.atlassian.com"
					logo={CustomLogoImage}
					icon={CustomIconImage}
					label="Home page"
				/>
			</TopNavStart>
		</MockTopBar>
	);
};

export default CustomLogoExample;

Custom title

Optional text used for app customisation by customers.

When present, it appears to the right of the logo.
It has a maximum width of 200px, after which the text truncates.
At s breakpoints and below (less than 1024px), the custom title is not displayed.

Jira

Custom title

import React from 'react';

import { JiraIcon } from '@atlaskit/logo/jira-icon';
import { TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';
import { AppLogo } from '@atlaskit/navigation-system/top-nav-items';
import { CustomTitle } from '@atlaskit/navigation-system/top-nav-items/custom-title';

import { MockTopBar } from '../common/mock-top-bar';

export const CustomTitleExample = (): React.JSX.Element => {
	return (
		<MockTopBar>
			<TopNavStart sideNavToggleButton={null}>
				<AppLogo href="http://www.atlassian.design" icon={JiraIcon} name="Jira" label="Home page" />
				<CustomTitle>Custom title</CustomTitle>
			</TopNavStart>
		</MockTopBar>
	);
};

export default CustomTitleExample;

Middle items

These actions go in the top nav middle area.

They should consist of a search component and a create component, in that order to maintain the correct layout behaviour.
The actions are center-aligned.
We have provided placeholder components. See navigation resources (Atlassians only), (opens new window) for recommended platform components.
Our placeholder search field scales to fill the available area of common actions, up to a maximum width of 780px. At xxs breakpoints (less than 480px), the search field converts to an icon only button.

See the responsive section for more information. If you use search or create components from other packages, you may experience different responsive behaviour.

The search bar must be the first child of TopNavMiddle, in line with our design specifications. Otherwise, you may see unexpected layout behavior.

import React from 'react';

import { TopNavMiddle } from '@atlaskit/navigation-system/layout/top-nav';
import { Search } from '@atlaskit/navigation-system/top-nav-items';
import { CreateButton } from '@atlaskit/navigation-system/top-nav-items/create-button';

import { MockTopBar } from '../common/mock-top-bar';

export function TopNavMiddleLayoutExample(): React.JSX.Element {
	return (
		<MockTopBar>
			<TopNavMiddle>
				<Search label="Search" />
				<CreateButton>Create</CreateButton>
			</TopNavMiddle>
		</MockTopBar>
	);
}

export default TopNavMiddleLayoutExample;

End items

These actions appear in the top nav end area. They are right-aligned and provided as a list for accessibility. Contains, in the following order:

Growth button - A placeholder for an upselling button (optional).
Chat - A placeholder for a chat panel.
Notifications - Use to open and close notifications.
Help - Use to open and close help.
Settings - Use to open and close a settings menu.
Profile/Login - A placeholder for an account component.

See navigation resources (Atlassians only), (opens new window) for recommended platform components for these buttons, or components triggered by these buttons.

At xs breakpoints and below (less than 768px), these buttons collapse into a single 'More' button.

See the responsive section for more details.

import React from 'react';

import Badge from '@atlaskit/badge/badge';
import { TopNavEnd } from '@atlaskit/navigation-system/layout/top-nav';
import { Help } from '@atlaskit/navigation-system/top-nav-items/help';
import { Notifications } from '@atlaskit/navigation-system/top-nav-items/notifications';
import { Settings } from '@atlaskit/navigation-system/top-nav-items/settings';

import { MockTopBar } from '../common/mock-top-bar';

export function TopNavEndLayoutExample(): React.JSX.Element {
	return (
		<MockTopBar>
			<TopNavEnd>
				<Notifications
					label="Notifications"
					badge={() => <Badge appearance="dangerBold">{3}</Badge>}
				/>
				<Help label="Help" />
				<Settings label="Settings" />
			</TopNavEnd>
		</MockTopBar>
	);
}

export default TopNavEndLayoutExample;

End item

If none of the provided end items are suitable, you can create your own icon button using EndItem.

If you need a more customised button, use top nav button and wrap it in a list item.

import React from 'react';

import AtlassianIntelligenceIcon from '@atlaskit/icon/core/atlassian-intelligence';
import { TopNavEnd } from '@atlaskit/navigation-system/layout/top-nav';
import { EndItem } from '@atlaskit/navigation-system/top-nav-items';

import { MockTopBar } from '../common/mock-top-bar';

export function EndItemExample(): React.JSX.Element {
	return (
		<MockTopBar>
			<TopNavEnd>
				<EndItem
					icon={AtlassianIntelligenceIcon}
					onClick={() => alert('Atlassian Intelligence')}
					label="Atlassian Intelligence"
				/>
			</TopNavEnd>
		</MockTopBar>
	);
}

export default EndItemExample;

Top nav button

A button component that supports theming. The following variants are available:

Top nav icon button
Top nav link button
Top nav link icon button
Top nav button

Use this component when you need to add buttons to the top nav. Be aware that adding custom buttons may negatively impact the consistency across apps.

import React from 'react';

import AiChatIcon from '@atlaskit/icon/core/ai-chat';
import TeamsIcon from '@atlaskit/icon/core/teams';
import { TopNav, TopNavEnd } from '@atlaskit/navigation-system/layout/top-nav';
import {
	TopNavButton,
	TopNavIconButton,
	TopNavLinkButton,
	TopNavLinkIconButton,
} from '@atlaskit/navigation-system/theming/top-nav-button';

import { MockRoot } from '../../utils/mock-root';

export const TopNavButtonExample = (): React.JSX.Element => (
	<MockRoot>
		<TopNav>
			<TopNavEnd>
				<TopNavIconButton icon={TeamsIcon} label="Top nav icon button" />
				<TopNavLinkIconButton
					icon={AiChatIcon}
					href="#example-href"
					label="Top nav link icon button"
				/>
				<TopNavLinkButton iconBefore={TeamsIcon} href="#example-href">
					Top nav link button
				</TopNavLinkButton>
				<TopNavButton iconBefore={AiChatIcon}>Top nav button</TopNavButton>
			</TopNavEnd>
		</TopNav>
	</MockRoot>
);

export default TopNavButtonExample;

Responsive

Top nav items respond to the viewport size. See the default behaviour below, or explore the interactive example.

Note: If using other platform components in top nav, they may have different responsive behaviour.

Breakpoint	Viewport	Start items	Middle items	End items
`xxs`	320 - 479px	Logo icon	Search icon button	'More' button
`xs`	480 - 767px	Logo icon	Search field	'More' button
`s`	768 - 1023px	Logo icon	Search field	All buttons
`m`	1024 - 1439px	Logo lockup	Search field	All buttons
`l`	1440 - 1767px	Logo lockup	Search field	All buttons
`xl`	1768+px	Logo lockup	Search field	All buttons

Custom theming

Custom theming is configured on the top nav.

Logos

Logos and icons from the logo package will automatically consume the theme when used with the AppLogo or CustomLogo component.

Custom logos uploaded by organization admins are not affected by theming.

Confluence

import React from 'react';

import { ConfluenceIcon } from '@atlaskit/logo/confluence-icon';
import { TopNav, TopNavStart } from '@atlaskit/navigation-system/layout/top-nav';
import { parseHex } from '@atlaskit/navigation-system/theming/color-utils/parse-hex';
import { AppLogo } from '@atlaskit/navigation-system/top-nav-items';

import { MockRoot } from '../../utils/mock-root';

export const CustomThemingLogoExample = (): React.JSX.Element => (
	<MockRoot>
		<TopNav
			customTheme={{ backgroundColor: parseHex('#964AC0'), highlightColor: parseHex('#F8EEFE') }}
		>
			<TopNavStart sideNavToggleButton={null}>
				<AppLogo
					icon={ConfluenceIcon}
					name="Confluence"
					label="Home page"
					href="https://atlassian.design"
				/>
			</TopNavStart>
		</TopNav>
	</MockRoot>
);

export default CustomThemingLogoExample;

Search

Use the useLegacySearchTheme() hook to obtain a theme value that is compatible with existing Search Platform components.

Use sparingly

Do not create new components that rely on the useLegacySearchTheme() hook. It is intended only for backwards compatibility, and may be deprecated if the Search Platform evolves.

import React from 'react';

import { TopNav, TopNavMiddle } from '@atlaskit/navigation-system/layout/top-nav';
import { parseHex } from '@atlaskit/navigation-system/theming/color-utils/parse-hex';
import { useLegacySearchTheme } from '@atlaskit/navigation-system/theming/use-legacy-search-theme';

import { MockRoot } from '../../utils/mock-root';
import { MockSearch } from '../../utils/mock-search';

const ThemedSearch = () => {
	const searchTheme = useLegacySearchTheme();
	return <MockSearch theme={searchTheme} />;
};

export const CustomThemingSearchExample = (): React.JSX.Element => (
	<MockRoot>
		<TopNav
			customTheme={{ backgroundColor: parseHex('#964AC0'), highlightColor: parseHex('#F8EEFE') }}
		>
			<TopNavMiddle>
				<ThemedSearch />
			</TopNavMiddle>
		</TopNav>
	</MockRoot>
);

export default CustomThemingSearchExample;

Buttons

Do not use button inside of the top navigation.

Use the action components exported from this package (such as AppSwitcher), as they automatically consume the custom theme.

Custom actions can be created using end item for icon buttons and top nav button for buttons with visible text.

import React from 'react';

import AngleBracketsIcon from '@atlaskit/icon/core/angle-brackets';
import { RovoIcon } from '@atlaskit/logo/rovo/icon';
import { TopNav, TopNavEnd } from '@atlaskit/navigation-system/layout/top-nav';
import { parseHex } from '@atlaskit/navigation-system/theming/color-utils/parse-hex';
import { TopNavButton } from '@atlaskit/navigation-system/theming/top-nav-button';
import { EndItem } from '@atlaskit/navigation-system/top-nav-items';

import { MockRoot } from '../../utils/mock-root';

export const CustomThemingButtonsExample = (): React.JSX.Element => (
	<MockRoot>
		<TopNav
			customTheme={{ backgroundColor: parseHex('#964AC0'), highlightColor: parseHex('#F8EEFE') }}
		>
			<TopNavEnd>
				<TopNavButton iconBefore={(props) => <RovoIcon {...props} size="xxsmall" label="" />}>
					Chat
				</TopNavButton>
				<EndItem icon={AngleBracketsIcon} label="Dev tools" />
			</TopNavEnd>
		</TopNav>
	</MockRoot>
);

export default CustomThemingButtonsExample;

Was this page helpful?

We use this feedback to improve our documentation.