Navbar

Usage

"use client";

import { Avatar } from "@thenamespace/uikit";
import { Navbar } from "@thenamespace/uikit";
import {

Anatomy

Import the Navbar component and access all parts using dot notation.

import { Navbar } from "@thenamespace/uikit";

<Navbar>
  <Navbar.Header>
    <Navbar.Brand />
    <Navbar.MenuToggle />
    <Navbar.Menu>
      <Navbar.MenuItem />
    </Navbar.Menu>
  </Navbar.Header>
  <Navbar.Content>
    <Navbar.Item />
    <Navbar.Label />
    <Navbar.Separator />
    <Navbar.Spacer />
  </Navbar.Content>
</Navbar>;

Docs Site

"use client";

import { Kbd, SearchField, Segment } from "@thenamespace/uikit";
import { Navbar } from "@thenamespace/uikit";
import {

A docs-site style navbar with a search bar, theme segment, and responsive mobile menu.

With Dropdowns

"use client";

import { Avatar, Button, Dropdown } from "@thenamespace/uikit";
import { Navbar } from "@thenamespace/uikit";
import { ArrowDown01Icon, Icon } from "@thenamespace/uikit/icons";

SaaS-style navbar with a team switcher, user dropdown, and mobile menu.

Dashboard

// @ts-nocheck -- Complex demo data intentionally uses heterogeneous shapes.
"use client";

import { useState } from "react";

Breadcrumb-style dashboard navbar built with InlineSelect for the workspace, project, and timezone selectors.

Compact

"use client";

import { Avatar, Button, Dropdown } from "@thenamespace/uikit";
import { Navbar } from "@thenamespace/uikit";
import { Icon, PlusSignIcon } from "@thenamespace/uikit/icons";

A dense navbar tuned via --spacing and height overrides for a Luma-style compact layout.

With Menu

"use client";

import { useState } from "react";

import { Avatar } from "@thenamespace/uikit";

Responsive navbar with a mobile hamburger toggle and animated dropdown menu.

Hide on Scroll

"use client";

import { useRef } from "react";

import { Avatar } from "@thenamespace/uikit";

Pass hideOnScroll to hide the navbar when the user scrolls down and reveal it on scroll up.

Responsive Mobile Menu

Navbar.MenuToggle and Navbar.Menu provide a built-in mobile dropdown. Use hidden md:flex on desktop-only groups and keep the toggle visible below the breakpoint:

<Navbar>
  <Navbar.Header>
    <Navbar.MenuToggle className="md:hidden" />
    <Navbar.Brand>…</Navbar.Brand>

    {/* Desktop-only nav */}
    <Navbar.Content className="hidden md:flex">
      <Navbar.Item href="/features">Features</Navbar.Item>
      <Navbar.Item href="/pricing">Pricing</Navbar.Item>
    </Navbar.Content>
  </Navbar.Header>

  {/* Mobile-only menu — animates in when the toggle is pressed */}
  <Navbar.Menu>
    <Navbar.MenuItem href="/features">Features</Navbar.MenuItem>
    <Navbar.MenuItem href="/pricing">Pricing</Navbar.MenuItem>
  </Navbar.Menu>
</Navbar>

The menu open state can be controlled via isMenuOpen / onMenuOpenChange on Navbar, or uncontrolled via defaultMenuOpen. By default the navbar locks body scroll while the menu is open — pass shouldBlockScroll={false} to disable.

Compact Density

Scale the entire navbar (paddings, gaps, icon sizes) by overriding the Tailwind v4 --spacing variable on the navbar or a wrapper, and tune the bar height with the height prop:

<Navbar
  height="2.75rem"
  size="sm"
  style={{ "--spacing": "0.22rem" } as React.CSSProperties}
>
  …
</Navbar>

• --spacing scales every Tailwind spacing utility (gap-*, p-*, size-*) inside the navbar
• height overrides the internal --navbar-height CSS variable
• size="sm" applies the built-in compact text + padding variants

Client-Side Routing

Navbar.Item renders a real <a> element when href is set (and Navbar.MenuItem does the same for the mobile menu), so it works with any router. You have three ways to integrate client-side routing:

Option 1 — Global RouterProvider (recommended)

Wrap your app once in React Aria's RouterProvider with your router's navigation function. Every Navbar.Item / Navbar.MenuItem with an href — along with any other Namespace UIKit component that links (e.g. Sidebar.MenuItem) — automatically routes through it, no per-Navbar navigate prop required. Modifier clicks (⌘/Ctrl-click) still open in a new tab, and external links keep their native behavior.

import { RouterProvider } from "react-aria-components";
import { Outlet, useHref, useNavigate } from "react-router";

export default function App() {
  const navigate = useNavigate();

  return (
    <RouterProvider navigate={navigate} useHref={useHref}>
      <main className="bg-background text-foreground min-h-dvh">
        <Outlet />
      </main>
    </RouterProvider>
  );
}

With the provider in place, the Navbar needs no routing props at all:

import { Navbar } from "@thenamespace/uikit";

export function AppNavbar() {
  return (
    <Navbar>
      <Navbar.Header>
        <Navbar.Brand>Acme</Navbar.Brand>
        <Navbar.Content>
          <Navbar.Item href="/features">Features</Navbar.Item>
          <Navbar.Item href="/pricing">Pricing</Navbar.Item>
        </Navbar.Content>
      </Navbar.Header>
    </Navbar>
  );
}

The RouterProvider navigate signature differs slightly per framework — see React Aria's client-side routing guide for Next.js, React Router, TanStack Router, Remix, and others.

Option 2 — navigate callback (per-Navbar)

When you don't have (or don't want) a global provider, pass your router's push function directly to Navbar. Every Navbar.Item / Navbar.MenuItem with an href routes through it. An explicit navigate prop always takes precedence over any global RouterProvider — useful when a navbar needs a different router (e.g. an external shell app).

Next.js (App Router)

"use client";

import { useRouter } from "next/navigation";
import { Navbar } from "@thenamespace/uikit";

export function AppNavbar() {
  const router = useRouter();

  return (
    <Navbar navigate={router.push}>
      <Navbar.Header>
        <Navbar.Brand>Acme</Navbar.Brand>
        <Navbar.Content>
          <Navbar.Item href="/features">Features</Navbar.Item>
          <Navbar.Item href="/pricing">Pricing</Navbar.Item>
        </Navbar.Content>
      </Navbar.Header>
    </Navbar>
  );
}

React Router

import { useNavigate } from "react-router";
import { Navbar } from "@thenamespace/uikit";

export function AppNavbar() {
  const navigate = useNavigate();

  return <Navbar navigate={navigate}>{/* ... */}</Navbar>;
}

TanStack Router

import { useRouter } from "@tanstack/react-router";
import { Navbar } from "@thenamespace/uikit";

export function AppNavbar() {
  const router = useRouter();

  return (
    <Navbar navigate={(href) => router.navigate({ to: href })}>
      {/* ... */}
    </Navbar>
  );
}

Option 3 — render prop for a custom link component

Since Navbar.Item and Navbar.MenuItem are polymorphic, you can swap the rendered element entirely to use a framework-specific <Link> component (preserving prefetch, scroll restoration, and any router-level behaviors):

import Link from "next/link";
import { Navbar } from "@thenamespace/uikit";

export function AppNavbar() {
  return (
    <Navbar>
      <Navbar.Header>
        <Navbar.Content>
          <Navbar.Item
            href="/features"
            render={(props) => <Link href="/features" {...props} />}
          >
            Features
          </Navbar.Item>
        </Navbar.Content>
      </Navbar.Header>
    </Navbar>
  );
}

Same works for Navbar.MenuItem in the mobile menu and for React Router's Link, TanStack Router's Link, etc.

Combine both approaches if you like — render owns the element/prefetch, and navigate is used as the fallback for programmatic navigations (e.g. closing the mobile menu and pushing to the href).

External Links and Force Reload

External URLs (starting with http:// or https://) are automatically opened in a new tab via window.open(href, "_blank", "noopener,noreferrer"). For internal links that need a full page reload instead of client-side navigation, use the forceReload prop:

<Navbar.Item href="https://github.com/namespace-inc/namespace">GitHub</Navbar.Item>

<Navbar.Item href="/legacy-page" forceReload>Legacy page</Navbar.Item>

Navigation resolution order: an explicit navigate prop wins, then a navigate inherited from an enclosing AppLayout, then a global React Aria RouterProvider, and finally the browser's default navigation if none are present.

Positioning

Use the position prop to control how the navbar is anchored:

• "sticky" (default) — sticks to the top of its scroll container (sticky top-0)
• "static" — flows inline with the page
• "floating" — sticky, but detached from the edges with rounded corners, margin, border, and a shadow

<Navbar position="floating" maxWidth="xl">
  …
</Navbar>

Programmatic Control

Use the useNavbar hook inside children of Navbar for programmatic access to the menu state and scroll-hidden state:

import { useNavbar } from "@thenamespace/uikit";

function CloseMenuButton() {
  const { isMenuOpen, setMenuOpen } = useNavbar();

  return (
    <Button onPress={() => setMenuOpen(false)} isDisabled={!isMenuOpen}>
      Close menu
    </Button>
  );
}

CSS Classes

Base & Variant Classes

• .navbar — Root <nav> element. Flex column, bg-background, z-40.
• .navbar--sticky — Sticky to the top of the scroll container.
• .navbar--static — Inline positioning.
• .navbar--floating — Sticky, detached with rounded-2xl, border, shadow-surface, and mx-2.
• .navbar[data-hidden="true"] — Applied while the navbar is hidden via hideOnScroll.
• .navbar[data-menu-open="true"] — Applied while the mobile menu is open.

Layout Classes

• .navbar__header — Horizontal bar wrapper. flex items-center gap-4 px-6, clamped by --navbar-max-width and --navbar-height.
• .navbar__header--max-sm|md|lg|xl|2xl|full — Sets --navbar-max-width to 640px / 768px / 1024px / 1280px / 1536px / 100%.
• .navbar__header--sm|md|lg — Size variants that tune --navbar-height and header padding.
• .navbar__brand — Logo / site-title container. flex shrink-0 items-center gap-2.
• .navbar__content — Horizontal group of items. flex items-center gap-1.
• .navbar__spacer — Flex-grow gap that pushes sibling content to the edges.

Item Classes

• .navbar__item — Nav link/button. text-muted text-sm, hover → text-foreground, rounded-lg.
• .navbar__item--sm|lg — Size variants for items (padding + font size).
• .navbar__item[data-current="true"] — Applied when isCurrent is true; bumps to text-foreground. Also sets aria-current="page".
• .navbar__label — Truncated text inside items.
• .navbar__separator — Vertical decorative divider (h-6 self-center).

Menu Classes

• .navbar__menu-toggle — Hamburger button (size-9). Toggles between hamburger and close icon via ::before/::after pseudo-elements.
• .navbar__menu-toggle--sm|lg — Size variants.
• .navbar__menu-toggle-icon — Inner span housing the animated pseudo-element lines.
• .navbar__menu — Mobile dropdown menu. flex flex-col gap-1 overflow-y-auto px-6 pb-6 pt-2. Height animates between 0 and calc(100dvh - var(--navbar-height)).
• .navbar__menu-item — Individual mobile menu item. text-foreground text-base font-medium, hover → bg-default.
• .navbar__menu-item--sm|lg — Size variants.
• .navbar__menu-item[data-current="true"] — Current mobile menu item (bg-default).

CSS Variables

• --navbar-height — Height of the horizontal bar (default: 4rem; 3rem for sm; 5rem for lg). Can also be set via the height prop on Navbar.
• --navbar-max-width — Max content width inside the header (default: 1024px, overridable via maxWidth).
• --navbar-transition-duration — Reserved for future transitions (default: 300ms).
• --spacing — Tailwind v4 base spacing token. Override on the navbar root (or a wrapper) to uniformly scale all internal paddings, gaps, and icon sizes.

Accessibility

• Rendered as a <nav> landmark. Add an aria-label when multiple navigation regions share the page.
• Navbar.Item with isCurrent sets aria-current="page" automatically.
• Navbar.MenuToggle is backed by RAC ToggleButton; its selected state is wired to isMenuOpen. Customize the screen-reader label via the srLabel prop.
• Animations respect the user's prefers-reduced-motion preference.

API Reference

Navbar

The root <nav> landmark and the context provider. Accepts all <nav> props.

Navbar.Header

Horizontal bar wrapper. Renders a <header> with the header size and max-width slot classes applied.

Navbar.Brand

Logo / site-title container. Polymorphic — accepts a render prop to customize the rendered element. Renders a <div> by default.

Navbar.Content

Horizontal group of nav items. Renders a <div>.

Navbar.Item

A single nav link or action. Renders an <a> when href is set, otherwise a <button>. Polymorphic via the render prop.

Navbar.Label

Truncated text span for use inside Navbar.Item.

Navbar.Separator

Vertical divider. Wraps Namespace UIKit Separator with orientation="vertical".

Navbar.Spacer

Flex-grow spacer that pushes surrounding content to opposite ends of the header.

Navbar.MenuToggle

Hamburger button for the mobile menu. Wraps RAC ToggleButton; its selected state is bound to isMenuOpen.

Navbar.Menu

Animated mobile dropdown. Only renders when isMenuOpen is true. Fills the viewport below the navbar with calc(100dvh - var(--navbar-height)).

Navbar.MenuItem

An individual item inside Navbar.Menu. Same API surface as Navbar.Item — but pressing an item automatically closes the mobile menu.

useNavbar

A hook for reading and mutating navbar state from inside Navbar's children.

const { height, isHidden, isMenuOpen, setMenuOpen, navigate } = useNavbar();