Topbar

v1.0.0 | View in Storybook It is composed of three regions: a left section for identity and breadcrumbs, an optional middle section for global navigation, and a right section for system controls. The structure and order of these regions is fixed and managed by Aura.

​

When to use

• Use the Topbar on every authenticated screen in a Cognite Data Fusion (CDF) or Flows custom app. There are no exceptions for screens that feel “simple” or single-purpose — if a user is authenticated and looking at an app view, a Topbar should be present.
• Use the middle navigation slot when your app has two or more top-level views or modes that users need to switch between globally. This applies both to multi-page apps (route-based tabs) and single-page apps (view or mode switching).
• Use the right action slot when an action is relevant on every page of the app — for example, a persistent “Add data” button that always applies regardless of what the user is looking at. In addition, show/hide the following system-controlled actions based on app requirements: Share, Notifications, Theme toggle, Atlas chat, Avatar.

​

When not to use

The Topbar may be omitted only on:

• login and auth-only screens.
• fullscreen flows or modals that explicitly hide all global chrome by design.
• shell-level exceptions documented by the platform team.
• when explicitly asked to be hidden by the product team.

​

Dos and don’ts

• Do use the Topbar’s middle section for primary global app navigation.
• Don’t use the Topbar’s action slot for page-specific actions. If a button only makes sense on one particular page or in one specific context, it belongs in the content area below the Topbar — not in the bar itself.
• Don’t reorder or restyle the system controls.
• Don’t use more than one Topbar per page.

​

Behavior

Left section:

• The left section is always present and always contains the same elements in the same order: application mark, breadcrumbs, and optional inline metadata.
• Application mark — a small Avatar primitive using the fjord colorway and size=“small”. Use the app image or branding from the app config when available, or leave it as the default avatar.
• Breadcrumbs — the app name is always the first segment. All breadcrumb segments are interactive links. When the user has a specific object open (a canvas, report, or document), that object’s name appears as the last segment. When an object is open, clicking the app name navigates back to the app’s home. When no object is open, the app name is plain text — not a link, because there is nowhere to navigate back to.
• An object dropdown may appear on the object name segment only, and only when an object is currently open. All actions in the dropdown must apply only to that object — no app-level actions should appear here. There is no dropdown on the app name.
• Inline metadata — an optional plain string immediately after the breadcrumb, such as “Updated 3 hours ago” or “Read-only”. This must be text only — no links, icons, or interactive elements. Omit it entirely when unused.

Middle section:

• This section is optional. Leave it empty if the app has only one view.
• Use Tabs when users are switching between distinct top-level pages or routes. Use a Segmented control when users are switching between modes or layouts within the same page. All controls here must be size=“small”.
• Do not place primary CTAs or app-specific action buttons in this section.

Right section:

• The right section contains system controls in a fixed order. Apps configure which controls are visible, but cannot change the order or styling of any control.
• Fixed order (left to right): Share → Notifications → Theme → Atlas.
  • Share, Notifications, Atlas are optional or dependent on the app’s configuration — show only the ones your app supports.
  • The theme toggle is always present for authenticated apps. The theme toggle shows a sun icon in light mode and a moon icon in dark mode. Clicking it opens a small menu with “Light mode” and “Dark mode” options, with a checkmark on the active choice.
  • All controls use size=“sm” and ghost styling except Atlas, which uses a secondary button with a leading icon and the label “Atlas”.

​

Visual examples

The examples below are interactive and follow the doc site’s theming: light mode when the docs site is in light mode, and dark mode when you switch the docs site to dark mode.

​

With breadcrumb dropdown

Use a breadcrumb dropdown on the object name when users need object-specific actions—for example, rename, duplicate, or delete the currently open item.

​

With center

Use the center section for global navigation when the app has two or more top-level views—for example, route-based tabs or mode switching within a single page.

​

Breadcrumb only

Use breadcrumb-only layout when the app has a single view and no global navigation tabs—for example, a simple detail page or a focused workflow.

​

Long content

Test long breadcrumb segments and metadata to ensure the left section truncates gracefully without pushing system controls off screen or breaking the layout.

​

With atlas action

Show the Atlas action in the right section when your app supports the Atlas chat integration—configure visibility based on app requirements and user permissions.

​

Surface with margin visual check

Use this example to verify Topbar spacing and surface treatment against page margins—ensure the bar aligns correctly with content below and respects layout padding.