# Navbar

The top bar in four scroll modes — static, sticky, hide on scroll, transparent — with mega menu, search, overflow and a mobile drawer.

- Category: Navigation & Layout
- Page: https://wunderui.com/components/navbar
- Tier: Core and Pro

## Install

Navbar ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { Navbar, BottomTabBar, MobileNav, NavbarLink, NavbarLinkProps, NavbarMenu, NavbarMenuFeatured, NavbarMenuGroup, NavbarMenuLink, NavbarMenuProps, NavbarMode, NavbarProps, NavbarSearch, NavbarSearchField, NavbarSearchProps, NotificationBell, ThemeToggle, UserMenu } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { Navbar, NavbarLink } from "@wunderui/react"

export function Header() {
  return (
    <Navbar logo={<span className="text-sm font-semibold text-foreground">WunderUI</span>}>
      <NavbarLink href="/overview" active>Overview</NavbarLink>
      <NavbarLink href="/projects">Projects</NavbarLink>
      <NavbarLink href="/reports">Reports</NavbarLink>
    </Navbar>
  )
}
```

Expected result: You see a 64 px bar with the logo and three links; Overview is tinted indigo. Scroll and the bar gets a shadow, and below 36rem the links give way to a menu button.

## When to use

### Use Navbar for

- The links across the top of a site or an app, with mega menus for grouped destinations
- Search, a command trigger, notifications and an account menu on the right
- A bar that reacts to scrolling: sticky, hiding or transparent over a hero

### Use something else

- [Sidebar](https://wunderui.com/components/sidebar) for a long list of app sections, with groups and a collapsible rail
- [App Layout](https://wunderui.com/components/app-layout) for the frame that holds the bar, a sidebar and the content
- [Tabs](https://wunderui.com/components/tabs) for switching views inside one page, not navigating between pages

## Keyboard

Every control is a native link or button, so the browser handles focus and activation. The mega menu is a disclosure: its panel is not modal and arrow keys do nothing.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves through the menu buttons, the links, More, the search icon, the command trigger and the actions in reading order. Focus shows as an indigo border with a 2 px ring. A closed mega menu panel is not in the tab order. |
| `Enter` or `Space` | On a link: follows it. On a mega menu button: opens or closes the panel. On the search icon: opens the field. |
| `ArrowRight` or `ArrowLeft` or `ArrowDown` or `ArrowUp` or `Home` or `End` | On the `icons` ThemeToggle: moves to the other theme and chooses it, wrapping around. Tab leaves the group again. |
| `Tab` | With a mega menu open: walks into the panel, link by link, and on to the next control. The panel is not modal. |
| `Esc` | Closes an open mega menu and returns focus to its button; hover cannot reopen it until the pointer has left. In the search field: closes it and returns focus to the icon. In the menu drawer: closes it and returns focus to the Open menu button. |
| `Enter` | In the search field: submits and calls `onSearch` with the text. |

ThemeToggle in its icons form is a radio group with one tab stop, the checked radio. Arrow keys, Home and End move between Light and Dark and choose as they go.

## Behavior

How the bar reacts to scrolling, to a narrow container and to a menu, and what it leaves to you.

- **Modes:** Sticky stays on top with a shadow on scroll, static scrolls away. Hide-on-scroll leaves going down and returns going up; transparent sits over a hero and turns solid after scrolling.
- **Scroll signal:** A zero-height marker tells whether the page is at the top, and the scroll direction is read once per frame. Both only set attributes on the header, so scrolling never re-renders React.
- **Hide on scroll:** The bar ignores jitter under 6 px and never hides before the page has scrolled by its own height. It stays while focus is inside or a mega menu is open, and with reduced motion it behaves as sticky.
- **Overflow:** The row measures every link's natural width. Links that do not fit move, from the end, into a More popover (mega menus never move), and a moved link keeps its current-page marking.
- **Order:** Mega menus are drawn before the links, whatever order you pass them in. Put the menus first in your code too, so the code reads like the bar.
- **Mega menu:** A mega menu opens on click, or on hover after 150 ms with a mouse, and a hover-opened panel closes 300 ms after the pointer leaves. One panel is open at a time, and a click outside closes it.
- **Search field:** The search field is a landmark named Sitewide. It widens from 36 px to 224 px and closes on Escape, or on blur when empty.
- **Command trigger:** NavbarSearch is a button that reports its click and does nothing else, so the key that opens your palette is yours to bind. It is hidden below 36rem.
- **Small screens:** The bar reads its own width, not the window. Below 36rem the links and command trigger hide and a menu button opens a left Sheet with the logo and every link, while search and actions stay in the bar.
- **Container, not window:** Because the bar reads its own width, a preview's Mobile width button narrows it like a phone. Parts that use the window width, such as side padding and the name in UserMenu, follow the window.
- **Semantics:** One header (the banner landmark), one nav named by the label, and a search landmark for the field. Icons and chevrons are hidden from assistive technology.

## Motion

Every transition uses the motion tokens and only changes transform, opacity, shadow and colour.

- **Lift:** Shadow and colours change quickly. Opacity is never animated on the bar, because it would kill the blur of the transparent mode.
- **Hide on scroll:** Only the position moves, for the base duration both ways, with an exit ease going out.
- **Mega menu:** The panel fades and moves one small step in, and leaves faster. The chevron turns 180 degrees.
- **Search field:** The width animates quickly.
- **Drawer:** The Sheet slides in from the left; mega menu disclosures inside it open their height.
- **Reduced motion:** With reduced motion the bar does not slide (hide-on-scroll is plain sticky), and the shadow, panel, search width and chevron change without a transition.

## Anatomy

- `Navbar`: The top bar: a sticky 64 px header with a bottom border. It lays out the logo, the link row and, pushed right, search, command trigger and actions, and the mode sets how it reacts to scrolling.
- `Logo`: The logo at the start of the bar, repeated by the menu drawer in its own header. Use one logo per screen, bar or sidebar.
- `Link row`: A nav named by the label (Main by default) with the mega menus first, then the links. Links that do not fit move into a More list; below 36rem the row gives way to the drawer.
- `NavbarSearchField`: Inline search: an icon button that widens into a 224 px field, named Sitewide. Enter submits, Escape closes it, and leaving it empty closes it.
- `NotificationBell`: A ghost icon button with a bell. Its name says the count (2 notifications) and a small indigo badge shows it, 99+ above 99.
- `UserMenu`: The account trigger: an avatar, an optional name and a chevron. It is a button named Account menu plus the name; use it as a Dropdown Menu trigger.
- `NavbarLink`: A top-level entry, 36 px high: a real link with an href, otherwise a button. The active link gets the indigo tint and is marked as the current page.
- `NavbarMenu`: A mega menu: a button that opens a rounded panel of links under the trigger, three rows by four columns at most (link count balances the columns). Optional footer link (View all) and featured column. It is a disclosure, not a menu role.
- `NavbarMenuLink`: One entry of a mega menu panel: a title, an optional description and an indigo icon tile. In the drawer it shrinks to the title.
- `NavbarMenuGroup`: A labelled column of a mega menu, like Product or Developers in Figma: a small label over a few links. Use one per column as direct children of NavbarMenu. In the drawer the label sits above its links.
- `NavbarMenuFeatured`: The featured column of a mega menu, passed as the featured prop: a gradient or picture over a title and a line of text. Hidden in the drawer.
- `More list`: A popover named More links that takes the links which do not fit. It lists links, not commands.
- `NavbarSearch`: A search-shaped button, never an input, for your command palette. It shows a shortcut hint and hides below 36rem, and the bar does not bind the key.
- `ThemeToggle`: Switches light and dark: a radio group of two icon buttons or a labelled switch. It reports the value and applies nothing.
- `Menu drawer`: A left Sheet below 36rem, opened by the Open menu button. It lists every link, and mega menus become disclosures.
- `MobileNav`: A separate 56 px bar for a phone screen: a menu button, a logo or title, and actions. It has no drawer of its own.
- `BottomTabBar`: A nav of icon and label tabs at the foot of a phone screen. The current tab is marked as the current page.
- `Navbar`
- `Notification Count`

## Best practices

### When to use

- Use Navbar for navigation across the top of a site or app: a handful of links, optional mega menus, search and account controls. For many app sections use a Sidebar; App Layout holds both.

### Do

- Pass NavbarLink and NavbarMenu as direct children, or as an array. The bar measures each child to decide what moves into More or the drawer, and a wrapper component hides them.
- Mark exactly one link as active. That is how a screen reader says where the person is.
- Give a link a real href when it goes to a page, so middle-click and open in a new tab work. Leave it out only for a client-side action.
- Name the landmark with a label as soon as a page has a second navigation. Main next to a sidebar is not enough.
- Give every icon control in the actions a name. The bell and account button name themselves; anything you add needs an aria-label.
- Use hide-on-scroll for long reading pages only. The bar stays while it holds focus or a menu is open, and with reduced motion it is plain sticky.

### Don't

- Don't put commands in NavbarMenu. It is a disclosure of links; use a Dropdown Menu for actions such as Sign out.
- Don't repeat the logo in a sidebar on the same screen. One logo per screen: bar or sidebar.
- Don't count on the shortcut hint of NavbarSearch. It only shows the keys; binding the key is up to you.

## API reference

### Navbar

| Prop | Type | Default | Description |
|---|---|---|---|
| actions | React.ReactNode |  | The cluster on the right: notifications, theme toggle, account menu or your own buttons. |
| children | React.ReactNode |  | `NavbarLink` and `NavbarMenu` entries, as direct children (an array is fine). Each can move into More or the drawer. |
| className | string |  | Extra classes for the `<header>`. |
| command | React.ReactNode |  | A `NavbarSearch` trigger for your command palette. Hidden below 36rem. |
| drawerTheme | "inherit" \| "dark" | "inherit" | Theme of the phone drawer (the Sheet's `theme`): `dark` for a dark or coloured bar on a light page. Default `inherit`. |
| label | string | "Main" | The name of the navigation landmark, `Main` by default. Set it as soon as the page has a second navigation; it also names the drawer. |
| logo | React.ReactNode |  | The logo at the start of the bar. The menu drawer repeats it in its header. |
| mode | "transparent" \| "static" \| "sticky" \| "hide-on-scroll" | "sticky" | `sticky` (default), `static`, `hide-on-scroll` or `transparent`. How the bar reacts to scrolling. |
| search | React.ReactNode |  | A `NavbarSearchField`, placed first among the utilities so it can grow without pushing the icons. |

### BottomTabBar

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | BottomTabBarItem[] |  | The tabs: `{ value, label, icon }` each. |
| onValueChange* | (value: string) => void |  | Called with the value of the tab that was pressed. |
| value* | string |  | The value of the current tab. It gets `aria-current="page"`. |

Also accepts React.HTMLAttributes attributes.

### MobileNav

| Prop | Type | Default | Description |
|---|---|---|---|
| actions | React.ReactNode |  | Buttons at the end of the bar. |
| hideMenu | boolean |  | Hides the menu button, for a screen with its own back button. |
| logo | React.ReactNode |  | A logo at the start. Use it or `title`. |
| onMenuClick | () => void |  | Called when the menu button is pressed. The bar has no drawer: open yours. |
| title | React.ReactNode |  | A page title instead of a logo, 16 px semibold. |

Also accepts React.HTMLAttributes attributes.

### NavbarLink

| Prop | Type | Default | Description |
|---|---|---|---|
| active | boolean |  | The current page: `aria-current="page"` and the indigo tint. One per bar. |
| href | string |  | Where the link goes. Without it the entry is a `<button>` for a client-side action. |

Also accepts React.AnchorHTMLAttributes attributes.

### NavbarMenu

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | `NavbarMenuLink` entries. Each is wrapped in a list item. |
| label* | React.ReactNode |  | The text of the button that opens the panel. |
| className | string |  | Extra classes for the wrapper of the button and its panel. |
| featured | React.ReactNode |  | A featured column at the end of the panel (Figma: Three columns). Pass a NavbarMenuFeatured. Hidden in the drawer. |
| footer | { label: React.ReactNode; href: string; onClick?: React.MouseEventHandler<HTMLAnchorElement> } |  | A "View all" link under a separator at the foot of the panel (Figma: Navigation / Item, kind View all link). |

### NavbarMenuFeatured

| Prop | Type | Default | Description |
|---|---|---|---|
| href* | string |  |  |
| title* | React.ReactNode |  |  |
| className | string |  |  |
| description | React.ReactNode |  |  |
| media | React.ReactNode |  | The picture or gradient above the text; defaults to the brand gradient. |
| onClick | React.MouseEventHandler<HTMLAnchorElement> |  |  |

### NavbarMenuGroup

| Prop | Type | Default |
|---|---|---|
| children* | React.ReactNode |  |
| label* | React.ReactNode |  |
| className | string |  |

### NavbarMenuLink

| Prop | Type | Default | Description |
|---|---|---|---|
| href* | string |  | Where the entry goes. Required: a mega menu holds links. |
| title* | React.ReactNode |  | The name of the destination. |
| className | string |  | Extra classes for the link. |
| description | React.ReactNode |  | One short line under the title. Not shown in the drawer. |
| icon | React.ReactNode |  | An icon for the 36 px tile at the start. Decorative; not shown in the drawer. |
| onClick | React.MouseEventHandler<HTMLAnchorElement> |  | Called on click, before the panel closes. Call `preventDefault` for client-side routing. |

### NavbarSearch

| Prop | Type | Default | Description |
|---|---|---|---|
| placeholder | string | "Search…" | The text of the trigger. `Search…` by default. |
| shortcut | string | "⌘K" | The key hint on the right, `⌘K` by default. Display only; the bar binds nothing. |
| variant | "plain" \| "outline" | "plain" | `plain` (default) is a muted pill; `outline` is a bordered field. |

Also accepts React.ButtonHTMLAttributes attributes.

### NavbarSearchField

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string |  | Extra classes for the form. The closed width is 36 px and the open width 224 px. |
| onSearch | (query: string) => void |  | Called with the text when the form is submitted. |
| placeholder | string | "Search" | The label and the placeholder of the field. `Search` by default. |

### NotificationBell

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the wrapper of the button and the badge. |
| count | number |  | The number of unread items. Above zero the name says it and a badge shows it, `99+` above 99. |
| expanded | boolean |  | Marks the trigger of an open popup: sets `aria-expanded` and the pressed surface. |
| focusableWhenDisabled | boolean | false | Keeps a disabled bell in the tab order. |
| nativeButton | boolean | true | Whether the rendered element is a native `<button>`. Set `false` when `render` gives another element. |
| pending | boolean |  | Shows a spinner in place of the bell and ignores presses. |
| phase | "error" \| "success" \| "pending" \| "idle" |  | `idle`, `pending`, `success` or `error`: the same square shows a spinner, a check or a retry icon. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Replaces the rendered element, for example with the trigger of a popover. |
| shape | "circle" \| "rounded" |  | `rounded` (default) or `circle`. |
| size | "lg" \| "xl" \| "sm" \| "md" \| "2xl" |  | `sm` 32 px, `md` 36 px (default), `lg`, `xl` or `2xl`. Use `sm` in the 64 px bar. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Inline styles for the button. |
| variant | "plain" \| "gradient" \| "outline" \| "primary" \| "destructive" \| "light" \| "ghost" \| "brand" \| "dark" |  | The icon button variant. `ghost` by default. |

Also accepts React.ButtonHTMLAttributes attributes.

### ThemeToggle

| Prop | Type | Default | Description |
|---|---|---|---|
| onValueChange* | (value: "light" \| "dark") => void |  | Called with the theme the person chose. Applying it is yours. |
| value* | "light" \| "dark" |  | The current theme, `light` or `dark`. |
| className | string |  | Extra classes for the group. |
| variant | "icons" \| "switch" | "icons" | `icons` (default) is a radio group with a sun and a moon, one tab stop and arrow-key navigation; `switch` is a row with a label and a switch. |

### UserMenu

| Prop | Type | Default | Description |
|---|---|---|---|
| avatar* | React.ReactNode |  | The avatar at the start, decorative. Name the person in `name`. |
| name | React.ReactNode |  | The name next to the avatar. Hidden below the `sm` breakpoint of the window. It becomes part of the accessible name. |
| variant | "rounded" \| "plain" | "rounded" | `rounded` (default) is a bordered pill, `plain` is the avatar and a chevron without a border. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Items: links, a mega menu, overflow

### Search: a field, a command trigger, both

### Actions: bell and account, theme, call to action

### Small screens: the drawer, a mobile bar, bottom tabs

## In context

### Marketing header: mega menus and one call to action

A menu opens on click, or on hover after 150 ms; Tab walks into the panel and Escape closes it and returns focus. Below 36rem the entries become disclosures in the drawer.

### App bar: links, command trigger, bell and account

The links switch the page and the current one is marked. The command trigger hides below 36rem, and the bell and account button open real pop-outs.

### Landing page: a transparent bar over the hero

The bar is a translucent layer with one blur over the hero and turns solid once the window scrolls. Pull the hero up by the bar's height and pad it equally.

### Docs header: inline search and a theme toggle

The search icon widens into a field; Enter submits, and Escape closes it and returns focus to the icon. The theme toggle reports the value, and applying it is up to you.

## For AI agents

`get_component("navbar")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
