@atlaskit/navigation-system/constellation/top-nav-items/usage.mdx

The latest navigation system for Atlassian apps.

---
title: Top nav items
description: Buttons and elements for the top nav.
order: 3
---

import Image from '@atlaskit/image';

import topNavItemsAnatomyLight from './images/topNavItems-anatomy-light.png';
import topNavItemsAnatomyDark from './images/topNavItems-anatomy-dark.png';
import topNavItemsDo1Light from './images/topNavItems-do-1-light.png';
import topNavItemsDo1Dark from './images/topNavItems-do-1-dark.png';
import topNavItemsDo2Light from './images/topNavItems-do-2-light.png';
import topNavItemsDo2Dark from './images/topNavItems-do-2-dark.png';
import topNavItemsDont1Light from './images/topNavItems-dont-1-light.png';
import topNavItemsDont1Dark from './images/topNavItems-dont-1-dark.png';
import topNavItemsDont2Light from './images/topNavItems-dont-2-light.png';
import topNavItemsDont2Dark from './images/topNavItems-dont-2-dark.png';

## Usage

Use top nav items to create common utilities in the top nav within
[layout](/components/navigation-system/layout/examples).

## Parts

<Image
	src={topNavItemsAnatomyLight}
	srcDark={topNavItemsAnatomyDark}
	alt="Diagram of the navigation system top nav"
/>

1. **Start items:** Left-aligned buttons.
2. **Middle items:** Centre-aligned actions.
3. **End items:** Right-aligned buttons.

## Follow Atlassian's navigation patterns

The current navigation has specific menu items that are similar across apps. Make sure your top
navigation follows Atlassian patterns consistently. For all the guidelines, see
[navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/spaces/navx/pages/5104144812).

## Accessibility

- Always provide a meaningful `label` for every top nav item. The label becomes the accessible name
  and the visible tooltip.
- When a top nav item triggers a popup, menu, or dialog, pass the relevant `aria-controls`,
  `aria-expanded`, and `aria-haspopup` props from that component to the top nav item.
- Use the `shortcut` prop to surface a keyboard shortcut in the tooltip when one exists. This makes
  the shortcut discoverable for keyboard users.
- Use `isSelected` to indicate when a corresponding popup or panel is open. This exposes the state
  to assistive technology.

## Best practices

### Use the top nav items provided

<DoDontGrid>
	<DoDont
		type="do"
		image={{
			url: topNavItemsDo1Light,
			urlDarkMode: topNavItemsDo1Dark,
			alt: 'Two buttons, one outlined and one solid purple, both labeled "Button".',
		}}
	>
		Use the top nav items provided.
	</DoDont>
	<DoDont
		type="dont"
		image={{
			url: topNavItemsDont1Light,
			urlDarkMode: topNavItemsDont1Dark,
			alt: 'Two buttons, one outlined and one solid purple, both labeled "Button".',
		}}
	>
		Don't use regular button in the top nav, as it won't respect custom theming.
	</DoDont>
</DoDontGrid>

### Don't add elements to the top nav area

<DoDontGrid>
	<DoDont
		type="do"
		image={{
			url: topNavItemsDo2Light,
			urlDarkMode: topNavItemsDo2Dark,
			alt: 'A segment of a top navigation bar showing standard Atlassian icons and a highlighted "ate" item.',
		}}
	>
		Use the top nav items as intended.
	</DoDont>
	<DoDont
		type="dont"
		image={{
			url: topNavItemsDont2Light,
			urlDarkMode: topNavItemsDont2Dark,
			alt: 'A segment of a top navigation bar showing standard Atlassian icons with an additional "Logout" button and a diamond icon.',
		}}
	>
		Don't add elements to the top nav, which may negatively impact consistency across apps.
	</DoDont>
</DoDontGrid>

## Related

- [Layout](/components/navigation-system/layout)
- [Navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE)