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

The latest navigation system for Atlassian apps.

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

import SectionMessage from '@atlaskit/section-message';

import { TopNavStartLayoutExample } from '../../examples/constellation/top-nav-items/top-nav-start';
import { TopNavStartToggleExample } from '../../examples/constellation/top-nav-items/top-nav-start-toggle';
import { TopNavMiddleLayoutExample } from '../../examples/constellation/top-nav-items/top-nav-middle';
import { TopNavEndLayoutExample } from '../../examples/constellation/top-nav-items/top-nav-end';
import { AppLogoExample } from '../../examples/constellation/top-nav-items/app-logo';
import { AppLogoSecondaryNameExample } from '../../examples/constellation/top-nav-items/app-logo-secondary-name';
import { CustomAppSwitcherExample } from '../../examples/constellation/top-nav-items/custom-app-switcher';
import { CustomLogoExample } from '../../examples/constellation/top-nav-items/custom-logo';
import { CustomThemingLogoExample } from '../../examples/constellation/top-nav-items/custom-theming--logo';
import { CustomThemingSearchExample } from '../../examples/constellation/top-nav-items/custom-theming--search';
import { CustomThemingButtonsExample } from '../../examples/constellation/top-nav-items/custom-theming--buttons';
import { EndItemExample } from '../../examples/constellation/top-nav-items/end-item';
import { TopNavButtonExample } from '../../examples/constellation/top-nav-items/top-nav-button';
import { CustomTitleExample } from '../../examples/constellation/top-nav-items/custom-title';

These components can be used within the top nav from
[layout](/components/navigation-system/layout/examples).

For other components that can be used within the top nav, see
[navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE).

## Start items

These actions go in the [top nav start](/components/navigation-system/layout/examples#top-nav-slots)
area. They are left-aligned in the following order:

- Side nav toggle button: Opens and closes the
  [side nav](/components/navigation-system/layout/examples#side-nav).
- App switcher: Opens and closes an app switcher. See
  [navigation resources (Atlassians only)](https://hello.atlassian.net/wiki/x/rBE7MAE) 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](#app-logo): A container for an app's [logo icon](/components/logo) and name.
- [Custom logo](#custom-logo): A container for custom logo images.
- [Custom title](#custom-title): Optional text used for app customisation by customers.

<Example Component={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.

<Example Component={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.

<Example Component={TopNavStartToggleExample} />

### App logo

App logo displays an app [logo icon](/components/logo) 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](#responsive) for more information.

<Example Component={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).

<Example Component={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](#responsive) for more information.

<Example Component={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.

<Example Component={CustomTitleExample} />

## Middle items

These actions go in the
[top nav middle](/components/navigation-system/layout/examples#top-nav-slots) 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)](https://hello.atlassian.net/wiki/x/rBE7MAE) 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](#responsive) for more information. If you use search or create
components from other packages, you may experience different responsive behaviour.

<SectionMessage>

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

</SectionMessage>

<Example Component={TopNavMiddleLayoutExample} />

## End items

These actions appear in the
[top nav end](/components/navigation-system/layout/examples#top-nav-slots) 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)](https://hello.atlassian.net/wiki/x/rBE7MAE) 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](#responsive) for more details.

<Example Component={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](#top-nav-button) and wrap it in a list
item.

<Example Component={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.

<Example Component={TopNavButtonExample} />

## Responsive

Top nav items respond to the viewport size. See the default behaviour below, or explore the
[interactive example](/components/navigation-system/examples#examples).

**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](/components/navigation-system/layout/custom-theming).

### Logos

Logos and icons from the [logo](/components/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.

<Example Component={CustomThemingLogoExample} />

### Search

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

<SectionMessage appearance="warning" title="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.

</SectionMessage>

<Example Component={CustomThemingSearchExample} />

### Buttons

Do not use [button](/components/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](#end-item) for icon buttons and
[top nav button](#top-nav-button) for buttons with visible text.

<Example Component={CustomThemingButtonsExample} />