# Navbar

Site navigation across the top of the page: the brand, a few links and the actions at the end. Below md the links move into a menu that slides in from the side. Links only: an application menu with commands is DropdownMenu, and an app with many sections uses Sidebar.

**Dependencies:** npm: 2 direct, 5 total; registry: 4 direct, 5 total.

## Usage

### When to use

- Link the few top-level pages of a site or a small app from the top of every page.
- Keep the brand, the main links and a sign-in or sign-up action in one row.

### When not to use

- An app with many sections or nested pages. Use Sidebar.
- Top-level navigation on a phone-first app. Use BottomNav.
- A menu of commands. Use DropdownMenu.

## Examples

### Site header

```tsx
<Navbar label="Main" className="w-full">
  <NavbarBrand href="#home">Acme</NavbarBrand>
  <NavbarLinks>
    <NavbarLink href="#overview" active>Overview</NavbarLink>
    <NavbarLink href="#customers">Customers</NavbarLink>
    <NavbarLink href="#reports">Reports</NavbarLink>
  </NavbarLinks>
  <NavbarActions>
    <Button variant="ghost">Sign in</Button>
    <Button>Get started</Button>
  </NavbarActions>
</Navbar>
```

### Links with icons

An icon goes before the text, 16px, and takes the accent on the current page.

```tsx
<Navbar label="Main" className="w-full">
  <NavbarBrand href="#home">Acme</NavbarBrand>
  <NavbarLinks>
    <NavbarLink href="#home" active>
      <IconHome size={16} />
      Home
    </NavbarLink>
    <NavbarLink href="#inbox">
      <IconInbox size={16} />
      Inbox
    </NavbarLink>
    <NavbarLink href="#settings">
      <IconSettings size={16} />
      Settings
    </NavbarLink>
  </NavbarLinks>
</Navbar>
```

## Do and don't

### Do

- Keep it to five links or fewer, each one or two words.
- Mark the current page with active, set from the router.
- Use sticky on long pages, so the links stay in reach.

### Don't

- Do not put commands (Save, Delete) in the links; links go somewhere.
- Do not use a Navbar and a Sidebar for the same links.
- Do not nest menus in the links; a site with deep sections needs Sidebar.

## Props

| Name | Type | Values | Default | Description |
| --- | --- | --- | --- | --- |
| `label` (required) | `string` |  |  | Set on Navbar. Names the navigation landmark, such as Main. |
| `menuLabel` | `string` |  | `Menu` | Set on Navbar. Name of the menu button below md, and the title of the menu it opens. |
| `sticky` | `boolean` |  | `false` | Set on Navbar. Sticks to the top of the scrolling page on a thin glass bar, keeping its line under it. |
| `active` | `boolean` |  | `false` | Set on NavbarLink. Marks the current page: aria-current="page" and the muted accent fill. |
| `asChild` | `boolean` |  | `false` | Set on NavbarLink or NavbarBrand. Renders the link look and behavior on its only child, such as a router link. |
| `href` | `string` |  |  | Set on NavbarLink or NavbarBrand. Where the link goes. |

### Slots

| Name | Required | Description |
| --- | --- | --- |
| `brand` | no | Children of NavbarBrand: a logo, a name or both. |
| `links` | no | Children of NavbarLinks: NavbarLink items, written once for both the row and the menu. |
| `actions` | no | Children of NavbarActions: one or two Buttons. |

## Anatomy

| Part | Description |
| --- | --- |
| `root` | The nav: one row, with a line under it. |
| `brand` | The link to the home page: a logo, a name or both. |
| `list` | The ul of links. From md up it sits after the brand; below md it moves into the menu as a column. |
| `link` | One link: text and an optional 16px icon, the current page on the muted accent fill. |
| `icon` | An optional icon in a link. |
| `menuButton` | The ghost icon button that opens the menu below md. |
| `actions` | Buttons at the end of the row, such as Sign in. |

## Accessibility

Role: `navigation`

| Keys | Action |
| --- | --- |
| `Tab` | Moves through the brand, the links (or the menu button below md) and the actions. |
| `Enter` | Follows the focused link, or opens the menu from the menu button. |
| `Escape` | Closes the menu and returns focus to the menu button. |

- A navigation landmark named by label, such as EN `Main`. Give it a different label from any other nav on the page.
- The links are a list. The current page's link has aria-current="page" and sets data-current.
- Below md the menu button is named by menuLabel (EN `Menu`, VI `Trình đơn`). The menu is a dialog titled by the same text, which traps focus while open.
- Following a link from the menu closes it.

## Install

```bash
npx werewolf-ui add navbar
```

Run `npx werewolf-ui init` once in your app before adding components. Init sets up tokens, their CSS import and agent rules. Add installs this component and its dependencies while preserving your theme. See [Installation](https://werewolf-ui.vercel.app/docs/installation.md) for requirements and the alternative registry setup.