Organisms

Top bar

The Dashboard shell chrome. A sticky 64px bar with a breadcrumb on the left and utilities on the right: Test mode switch, Theme toggle, Notifications bell, Account menu.

Updated Jul 16, 2026 by Leonardo Posada

Live preview

Page content
<TopBar breadcrumb="Home" />

Anatomy

The top bar has two zones separated by justify-between. Left: breadcrumb text (single item, no chevron). Right: a group of utilities separated by vertical dividers, ending with the avatar dropdown.

  1. 1
    Breadcrumb

    Left-side path. Accepts a string (single-item) or an array of segments to render a CaretRight (light, size-3) chevron chain. The last segment is text-foreground (current section); earlier segments are text-muted-foreground and become clickable buttons if onClick is passed.

  2. 2
    Theme toggle

    Sun / Moon icon button. Toggles the .dark class on <html>.

  3. 3
    Notifications bell

    IconButton with BellSimple (light). Opens the notification tray in real Dashboard.

  4. 4
    GlobalChip

    Environment + scope switcher chip. Opens a dropdown with ENVIRONMENT and ACCOUNTS sections. See the dedicated /organisms/global-chip page for full anatomy.

  5. 5
    AccountMenu

    Avatar dropdown with profile actions. See the dedicated /organisms/account-menu page for full anatomy.

  6. 6
    Test mode switch (optional, default off)

    Kit Switch labeled 'Test mode'. Opt-in via showTestMode={true}. When on, the account is operating in sandbox; wire host to actually swap keys.

  7. 7
    Dividers

    Vertical Separator h-6 between each utility group so the utilities read as distinct clusters.

Breadcrumb

The breadcrumb slot accepts either a plain string (single item) or an array of segments. Segments render as a CaretRight-separated chain, and any segment with an onClick becomes a hoverable button. The last segment is always the current section (non-clickable, text-foreground).

Single string — landing pages
<TopBar breadcrumb="Home" />
Segment array — detail views inside a section
<TopBar
  breadcrumb={[
    { label: "Risk conditions", onClick: () => router.push("/risk-conditions") },
    { label: "Rules", onClick: () => router.push("/risk-conditions/rules") },
    { label: "r-005" },
  ]}
/>
  • Single-string form for landing pages (Home, Insights) where there's no parent path.
  • Segment array for detail views inside a section (Risk conditions › Rules › r-005).
  • Only the last segment gets text-foreground — every previous segment is text-muted-foreground.
  • Parent segments should be clickable back to their own list — don't leave the trail dead.
  • Never nest a menu or dropdown inside a segment — the breadcrumb is for wayfinding only.

When to use

  • As the sticky top of any Dashboard-adjacent prototype (pair with Sidebar).
  • Prototypes that need Test mode toggle, notifications, or account menu.
  • When the flow spans multiple pages of the same Dashboard shell.

When not to use

  • Marketing landings — use a marketing top nav.
  • Focused modals or wizards — hide the shell entirely.
  • As a page-title header — use PageHeader below the top bar instead.

Usage

Do
  • Keep the top bar sticky (sticky top-0 z-20) so it stays anchored while content scrolls.
  • Order utilities right-to-left by frequency: avatar last, notifications and theme in the middle, Test mode as the outermost feature.
  • Use the kit Switch and Separator inside — never redeclare a bespoke switch.
  • Fill the breadcrumb with the current section (matches the sidebar selection).
Don't
  • Don't add a title or logo inside the top bar — logo lives in the Sidebar.
  • Don't nest actions or menus inside the breadcrumb slot.
  • Don't stack more than 4 utilities on the right — trim rare ones into the account menu.
  • Don't rename Test mode to 'Sandbox' or 'Preview' — the copy is canonical.

Composition

TopBar is sticky (position: sticky). Render it as the first child of your page content, after the Sidebar, so it hovers above scroll.

See the code block below for the shell pattern.
import { TopBar } from "@/components/organisms/top-bar";
import { Sidebar } from "@/components/organisms/sidebar";

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="min-h-screen">
      <div className="fixed inset-y-0 left-0 z-30">
        <Sidebar />
      </div>
      <div className="pl-64">
        <TopBar breadcrumb="Home" />
        <main>{children}</main>
      </div>
    </div>
  );
}

Common configurations

Four canonical ways the TopBar shows up in Yuno prototypes: the default Dashboard shell, a custom-scope session, a Test-mode session, and a read-only variant with utilities stripped down. Copy the closest one and tweak.

Default shell top bar

The everyday Dashboard chrome: Home breadcrumb, GlobalChip visible, notifications on, Test mode off. Use in any prototype that sits inside the real Dashboard shell.

<TopBar breadcrumb="Home" />
Custom scope + account menu

Override the account identity and swap the account list on the GlobalChip. Use when the prototype needs a specific org/account picker (e.g. Tiendamia BR / AR) or a named user.

<TopBar
  breadcrumb="Payments"
  accountMenu={{ userName: "Julián Núñez", userEmail: "julian@y.uno" }}
  globalChip={{
    organizationLabel: "Tiendamia",
    accounts: [
      { key: "tiendamia-br", label: "Tiendamia BR", meta: "Brazil" },
      { key: "tiendamia-ar", label: "Tiendamia AR", meta: "Argentina" },
    ],
    onApply: ({ keys }) => router.push(`/accounts/${keys[0]}`),
  }}
/>
With Test mode switch visible

Opt in to the Test mode switch and drop the GlobalChip into Sandbox with a test account. Use for prototypes that must communicate 'you are not in production' at all times.

Test mode
<TopBar
  breadcrumb="Rules"
  showTestMode
  globalChip={{
    defaultEnv: "test",
    accounts: [
      { key: "test-account", label: "Test account", meta: "Sandbox" },
    ],
  }}
/>
Read-only (no utilities)

Hide notifications and the GlobalChip when the prototype is an embed, a screenshot fixture, or a single-account demo where nothing can be switched. Theme toggle and account menu stay.

<TopBar
  breadcrumb="Insights"
  showNotifications={false}
  showGlobalChip={false}
/>

Import

Copy this import line at the top of the file where you compose the shell. TopBar is self-contained: it owns its own Test-mode state, GlobalChip, and AccountMenu — no provider needed at the app root.

Single import: the TopBar owns its own Test-mode state, theme toggle wiring, GlobalChip, and AccountMenu — no provider needed.
import { TopBar } from "@/components/organisms/top-bar";

Props

TopBar is a fixed 64px chrome with a breadcrumb slot on the left and a compound utility cluster on the right. You configure what's visible via boolean toggles, and pass config objects to the two composed organisms (AccountMenu and GlobalChip). All layout concerns (sticky positioning, z-index, page-column offset) are canonical and should not be overridden through className.

PropTypeDefaultDescription
breadcrumbstring | BreadcrumbSegment[]"Home"Left-side path. String renders a single non-clickable segment. Array renders a CaretRight-separated chain: the last segment is the current section (text-foreground); earlier segments become buttons when they define onClick.
accountMenuAccountMenuProps—Forwarded to <AccountMenu />. Overrides the default user card (userName, userEmail, initial, accountsCount). Omit to render the demo account.
showTestModebooleanfalseToggles the 'Test mode' Switch + its divider. Off by default to match the current Dashboard. When enabled, the switch owns its own state — the host must wire the real key swap.
showNotificationsbooleantrueToggles the notifications bell + its divider. Turn off for read-only or embedded shells where notifications don't apply.
showGlobalChipbooleantrueToggles the GlobalChip (environment + scope switcher) + its divider. Turn off for single-account prototypes with nothing to switch.
globalChipGlobalChipProps—Forwarded to <GlobalChip />. Configure organizationLabel, organizationAccounts, groups[], accounts[], recentKeys, defaultEnv, and the onApply / onSaveAsGroup handlers.
classNamestring—Merged onto the outer <header> via cn(). Use sparingly — the sticky positioning, 64px height, and horizontal padding are canonical and should not be overridden.

Related

Cross-links to atoms and patterns you may reach for next.

  • SidebarPairs with the Top bar to form the full Dashboard shell.
  • Page headerPage-level title block that sits inside content, right below the top bar.
  • Account menuAvatar dropdown embedded at the far right of the top bar.
  • Global chipEnvironment + scope switcher embedded in the top bar.
  • TooltipLabels the IconButton actions (notifications, theme) on hover.
  • IconographyPhosphor icons used for the utilities: light default, fill for active.
  • Colorsborder-border for the bottom rule, bg-background for the surface.