Prepared Docs

Overview

Navbar is the application-level top bar for operator consoles. It combines product identity, primary route destinations, optional app switching, and persistent utilities in one named navigation landmark. The mental model is "stable top chrome owned by the app": Navbar supplies structure and responsive behavior while the app owns routes, permissions, labels, counters, and selection state.

When to use

App-level top chrome that needs a named navigation landmark with distinct start and end regions.
Desktop-first consoles with a compact set of peer destinations and persistent account or utility actions.
Multi-app shells that need to switch products without changing the overall chrome pattern.
Branded or whitelabel products that share navigation behavior but display different product identity.

When not to use

In-page section navigation—use TabNav for route-backed links or Tabs for panels on one page.
A long or hierarchical list of primary modules—use Sidebar.
Selection-scoped bulk actions—use Toolbar.
A public marketing header with freeform layouts or promotional content; Navbar is constrained application chrome.

Composition

Compose NavbarStart and NavbarEnd inside Navbar. Place NavbarBrand and NavbarTabs in the start region. Place selectors, account controls, and one or more NavbarGroups in the end region. NavbarGroup adds a full-height separator before a related action cluster.

NavbarTabs accepts an ordered app-owned model rather than arbitrary children. Visible tabs, the hidden measurement row, and the overflow menu share that model; custom renderTab output stays in the visible row, while measurement uses renderMeasurementTab or an inert default tab. A measurement stand-in can be any single element; overflow measures that node even when it is not an anchor.

Account menus are app composition, not a Navbar primitive. Compose an avatar, a visible name that truncates only after --pr-navbar-account-name-max-width (12rem default), and a decorative chevron that rotates when the menu is open. Include the visible name in the trigger accessible name, for example "Alex Rivera, Account." Click-open is the default. Hover-open is opt-in. Reserve ChevronUpDown for the app switcher; that icon path-morphs each arrow inward while the menu is open, which is a different motion from the single ChevronDown rotation on More and account triggers.

Variants

Logo brand. Pass a logo or product mark to NavbarBrand and provide ariaLabel.
Text brand. Use variant="text" for a concise whitelabel or product name.
Multi-app brand. Set multiApp and provide apps, currentApp, onSelectApp, and appMenuLabel. The current app appears beside the brand in a radio menu.
Responsive tabs. Keep overflow enabled for normal application chrome. Set overflow={false} only when the surrounding layout guarantees every destination fits.

Content guidelines

Keep destination labels short, sentence-case, and parallel. Use the same vocabulary in page titles, breadcrumbs, and side navigation.
Localize Navbar labels, tab labels, app names, counters, action names, overflowMenuLabel, and appMenuLabel at the call site.
Write appMenuLabel as an action phrase such as "Switch app." The component combines it with the visible current app name so the accessible name preserves label-in-name.
Use counters for concise attention signals. Do not place status sentences or rapidly changing prose in tab labels.
Give icon-only actions clear accessible names that describe the action, not the icon.

Behavior and states

Active destination. currentPath determines the active tab. Use extraRouteMatchers when one destination represents multiple nested routes.
Responsive overflow. Tabs that do not fit move into a labeled More menu that sits beside the last visible tab. The More label and chevron use alt color and transition to base together on hover, matching inactive TabNav destinations. The menu opens on click by default. Set overflowMenuOpenOnHover only when the product explicitly wants hover-open; click remains available. The active destination remains visible when possible, and every hidden destination remains available from the menu. Hidden current destinations expose aria-current="page" on their menu row.
Portaled overflow interactions. Custom overflow rows that open secondary portaled UI call onInteractingChange(true) while pointer or focus remains in the row or its portaled UI. Interaction ending alone does not dismiss More. Outside events are suppressed while interaction is active; onSelect, Escape, or a deferred hover dismiss closes the menu. Call onInteractingChange(false) when the interaction ends and during unmount cleanup. Wire onSelect to the in-menu NavMenuItem for destination activation; do not call it from portaled close actions. See the Prepared911TopNav and MultiApp Storybook examples for end-to-end overflow behavior.
Account menu. Apps own the account trigger. Keep the visible name in the accessible name, treat the chevron as decorative, and default to click-open. Hover-open is the same opt-in as overflow. Cap the name with --pr-navbar-account-name-max-width so shorter names stay fully visible.
Resize. Available space is remeasured when the start region changes size, including when branding, trailing actions, or the viewport changes.
Navigation. Apps supply navigate and remain responsible for route transitions, guards, and unsaved-work handling.
Permissions. Filter unavailable destinations and apps before passing the ordered models. Do not expose a disabled or hidden route without an explanatory alternative.
App switching. The app updates currentApp, available destinations, and the active route together. Avoid leaving a tab selected that does not belong to the newly selected app.

Best practices

Keep high-frequency destinations visible and early in the ordered tab model.
Group related trailing actions and preserve a stable order across sessions.
Test the longest expected translation and constrained widths.
Keep the same product identity and destination order long enough to build operator muscle memory.

Don't

Put destructive or uncommon actions directly in the primary destination row.
Duplicate every Navbar destination in a Sidebar without an information-architecture reason.
Hide overflowed destinations or rely on hover alone to reveal them.
Store routing, permissions, or product data inside the design-system component.

Accessibility

Give every Navbar a product-language ariaLabel, every logo brand an ariaLabel, and every icon-only action a discernible name. Tabs remain real links, while the app switcher and overflow use keyboard-operable menus. See Accessibility for the full contract.

Tab nav for route-backed navigation within a feature.
Tabs for panel selection on one route.
Sidebar for persistent hierarchical application navigation.
Toolbar for contextual action clusters.
Page header for page titles, metadata, and page-scoped actions below global chrome.

Accessibility / Disabled States

Navbar / API and Development

Overview

When to use

App-level top chrome that needs a named navigation landmark with distinct start and end regions.
Desktop-first consoles with a compact set of peer destinations and persistent account or utility actions.
Multi-app shells that need to switch products without changing the overall chrome pattern.
Branded or whitelabel products that share navigation behavior but display different product identity.

When not to use

In-page section navigation—use TabNav for route-backed links or Tabs for panels on one page.
A long or hierarchical list of primary modules—use Sidebar.
Selection-scoped bulk actions—use Toolbar.
A public marketing header with freeform layouts or promotional content; Navbar is constrained application chrome.

Composition

Variants

Logo brand. Pass a logo or product mark to NavbarBrand and provide ariaLabel.
Text brand. Use variant="text" for a concise whitelabel or product name.
Multi-app brand. Set multiApp and provide apps, currentApp, onSelectApp, and appMenuLabel. The current app appears beside the brand in a radio menu.
Responsive tabs. Keep overflow enabled for normal application chrome. Set overflow={false} only when the surrounding layout guarantees every destination fits.

Content guidelines

Keep destination labels short, sentence-case, and parallel. Use the same vocabulary in page titles, breadcrumbs, and side navigation.
Localize Navbar labels, tab labels, app names, counters, action names, overflowMenuLabel, and appMenuLabel at the call site.
Write appMenuLabel as an action phrase such as "Switch app." The component combines it with the visible current app name so the accessible name preserves label-in-name.
Use counters for concise attention signals. Do not place status sentences or rapidly changing prose in tab labels.
Give icon-only actions clear accessible names that describe the action, not the icon.

Behavior and states

Active destination. currentPath determines the active tab. Use extraRouteMatchers when one destination represents multiple nested routes.
Responsive overflow. Tabs that do not fit move into a labeled More menu that sits beside the last visible tab. The More label and chevron use alt color and transition to base together on hover, matching inactive TabNav destinations. The menu opens on click by default. Set overflowMenuOpenOnHover only when the product explicitly wants hover-open; click remains available. The active destination remains visible when possible, and every hidden destination remains available from the menu. Hidden current destinations expose aria-current="page" on their menu row.
Portaled overflow interactions. Custom overflow rows that open secondary portaled UI call onInteractingChange(true) while pointer or focus remains in the row or its portaled UI. Interaction ending alone does not dismiss More. Outside events are suppressed while interaction is active; onSelect, Escape, or a deferred hover dismiss closes the menu. Call onInteractingChange(false) when the interaction ends and during unmount cleanup. Wire onSelect to the in-menu NavMenuItem for destination activation; do not call it from portaled close actions. See the Prepared911TopNav and MultiApp Storybook examples for end-to-end overflow behavior.
Account menu. Apps own the account trigger. Keep the visible name in the accessible name, treat the chevron as decorative, and default to click-open. Hover-open is the same opt-in as overflow. Cap the name with --pr-navbar-account-name-max-width so shorter names stay fully visible.
Resize. Available space is remeasured when the start region changes size, including when branding, trailing actions, or the viewport changes.
Navigation. Apps supply navigate and remain responsible for route transitions, guards, and unsaved-work handling.
Permissions. Filter unavailable destinations and apps before passing the ordered models. Do not expose a disabled or hidden route without an explanatory alternative.
App switching. The app updates currentApp, available destinations, and the active route together. Avoid leaving a tab selected that does not belong to the newly selected app.

Best practices

Keep high-frequency destinations visible and early in the ordered tab model.
Group related trailing actions and preserve a stable order across sessions.
Test the longest expected translation and constrained widths.
Keep the same product identity and destination order long enough to build operator muscle memory.

Don't

Put destructive or uncommon actions directly in the primary destination row.
Duplicate every Navbar destination in a Sidebar without an information-architecture reason.
Hide overflowed destinations or rely on hover alone to reveal them.
Store routing, permissions, or product data inside the design-system component.

Accessibility

Tab nav for route-backed navigation within a feature.
Tabs for panel selection on one route.
Sidebar for persistent hierarchical application navigation.
Toolbar for contextual action clusters.
Page header for page titles, metadata, and page-scoped actions below global chrome.

Accessibility / Disabled States

Navbar / API and Development