React Navbar: examples and API

Preview

Live preview

Changes apply to this preview only.

Width adapts to the available space

"use client";

import { useState } from "react";
import {
  Badge,
  Navbar,
  NavbarActions,
  NavbarBrand,
  NavbarContent,
  NavbarItem,
  NavbarToggle
} from "@pimolu/react";

export function NavbarExample() {
  const [active, setActive] = useState("Overview");
  return (
    <div className="space-y-5">
      <Navbar collapsible>
        <NavbarBrand href="#navigation-example">Orbit</NavbarBrand>
        <NavbarToggle openLabel="Open example menu" closeLabel="Close example menu" />
        <NavbarContent aria-label="Example navigation">
          {
            ["Overview", "Projects"].map((label) => <NavbarItem
              key={label}
              href="#navigation-example"
              active={active === label}
              onClick={(event) => { event.preventDefault(); setActive(label); }}
            >
              {
                label
              }
            </NavbarItem>)
          }
        </NavbarContent>
        <NavbarActions>
          <Badge variant="success">Workspace</Badge>
        </NavbarActions>
      </Navbar>
      <p id="navigation-example" role="status">Current view: {active}.</p>
    </div>
  );
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Choose a surface, blend into the page, or use a floating frame. The transparent appearance avoids side edges caused by an inset background.

Open preview

Brand, links and actions; the active link is marked for assistive technology.

Open preview

Both examples use the same Navbar API. Open the menu to see links and actions; selecting a link closes it. The layout responds to the navbar's own width.

Open preview

Usage

Compose NavbarBrand, NavbarContent, NavbarItem and NavbarActions. Enable collapsible and include NavbarToggle for narrow containers. Choose appearance=surface, transparent or floating; bordered controls the bottom divider while floating keeps its surrounding frame.

NavbarToggle accepts custom icon and closeIcon nodes. Control open/onOpenChange when route changes or another part of your app should close the menu.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluNavbarProps

Type source

PimoluNavbarProps public API
Name	Type	Default	Description
`appearance`	`"surface" \| "transparent" \| "floating" \| undefined`	`surface; transparent inherits the page background`	Surface treatment. Defaults to surface; transparent inherits the page background.
`sticky`	`boolean \| undefined`	`false`	Stick to the top of the scroll container.
`bordered`	`boolean \| undefined`	`true`	Draw the bottom border. Defaults to true.
`itemsPosition`	`"left" \| "right" \| "center" \| undefined`	`"left"`	Alignment of the navigation items inside the bar. Defaults to "left". The brand stays at the start and the actions at the end.
`collapsible`	`boolean \| undefined`	`false`	Collapse links and actions behind NavbarToggle in narrow containers.
`open`	`boolean \| undefined`	—	Controlled mobile menu state.
`defaultOpen`	`boolean \| undefined`	`false`	Initial mobile menu state when uncontrolled.
`onOpenChange`	`((open: boolean) => void) \| undefined`	—	Public Pimolu prop; see the source declaration for details.
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`onChange`	`ChangeEventHandler<HTMLElement, Element> \| undefined`	—	Standard React/HTML attribute.
`onClick`	`MouseEventHandler<HTMLElement> \| undefined`	—	Standard React/HTML attribute.

appearance: "surface" | "transparent" | "floating" | undefined
Default: surface; transparent inherits the page background
Surface treatment. Defaults to surface; transparent inherits the page background.
sticky: boolean | undefined
Default: false
Stick to the top of the scroll container.
bordered: boolean | undefined
Default: true
Draw the bottom border. Defaults to true.
itemsPosition: "left" | "right" | "center" | undefined
Default: "left"
Alignment of the navigation items inside the bar. Defaults to "left". The brand stays at the start and the actions at the end.
collapsible: boolean | undefined
Default: false
Collapse links and actions behind NavbarToggle in narrow containers.
open: boolean | undefined
No default extracted.
Controlled mobile menu state.
defaultOpen: boolean | undefined
Default: false
Initial mobile menu state when uncontrolled.
onOpenChange: ((open: boolean) => void) | undefined
No default extracted.
Public Pimolu prop; see the source declaration for details.
childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
onChange: ChangeEventHandler<HTMLElement, Element> | undefined
No default extracted.
Standard React/HTML attribute.
onClick: MouseEventHandler<HTMLElement> | undefined
No default extracted.
Standard React/HTML attribute.

PimoluNavbarBrandProps

Type source

PimoluNavbarBrandProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`type`	`string \| undefined`	`"button"`	Standard React/HTML attribute.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`onChange`	`ChangeEventHandler<HTMLAnchorElement, Element> \| undefined`	—	Standard React/HTML attribute.
`onClick`	`MouseEventHandler<HTMLAnchorElement> \| undefined`	—	Standard React/HTML attribute.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
type: string | undefined
Default: "button"
Standard React/HTML attribute.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
onChange: ChangeEventHandler<HTMLAnchorElement, Element> | undefined
No default extracted.
Standard React/HTML attribute.
onClick: MouseEventHandler<HTMLAnchorElement> | undefined
No default extracted.
Standard React/HTML attribute.

PimoluNavbarContentProps

Type source

PimoluNavbarContentProps public API
Name	Type	Default	Description
`aria-label`	`string \| undefined`	—	Accessible name of the navigation landmark.
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`onChange`	`ChangeEventHandler<HTMLElement, Element> \| undefined`	—	Standard React/HTML attribute.
`onClick`	`MouseEventHandler<HTMLElement> \| undefined`	—	Standard React/HTML attribute.

aria-label: string | undefined
No default extracted.
Accessible name of the navigation landmark.
childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
onChange: ChangeEventHandler<HTMLElement, Element> | undefined
No default extracted.
Standard React/HTML attribute.
onClick: MouseEventHandler<HTMLElement> | undefined
No default extracted.
Standard React/HTML attribute.

PimoluNavbarToggleProps

Type source

PimoluNavbarToggleProps public API
Name	Type	Default	Description
`icon`	`ReactNode`	—	Replaces the default hamburger icon.
`closeIcon`	`ReactNode`	—	Replaces the default close icon.
`openLabel`	`string \| undefined`	`"Open menu"`	Accessible label while the menu is closed.
`closeLabel`	`string \| undefined`	`"Close menu"`	Accessible label while the menu is open.
`onChange`	`ChangeEventHandler<HTMLButtonElement, Element> \| undefined`	—	Standard React/HTML attribute.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`onClick`	`MouseEventHandler<HTMLButtonElement> \| undefined`	—	Standard React/HTML attribute.
`disabled`	`boolean \| undefined`	`false`	Standard React/HTML attribute.
`name`	`string \| undefined`	—	Standard React/HTML attribute.
`type`	`"submit" \| "reset" \| "button" \| undefined`	`"button"`	Standard React/HTML attribute.
`value`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.

icon: ReactNode
No default extracted.
Replaces the default hamburger icon.
closeIcon: ReactNode
No default extracted.
Replaces the default close icon.
openLabel: string | undefined
Default: "Open menu"
Accessible label while the menu is closed.
closeLabel: string | undefined
Default: "Close menu"
Accessible label while the menu is open.
onChange: ChangeEventHandler<HTMLButtonElement, Element> | undefined
No default extracted.
Standard React/HTML attribute.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
onClick: MouseEventHandler<HTMLButtonElement> | undefined
No default extracted.
Standard React/HTML attribute.
disabled: boolean | undefined
Default: false
Standard React/HTML attribute.
name: string | undefined
No default extracted.
Standard React/HTML attribute.
type: "submit" | "reset" | "button" | undefined
Default: "button"
Standard React/HTML attribute.
value: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.

PimoluNavbarItemProps

Type source

PimoluNavbarItemProps public API
Name	Type	Default	Description
`active`	`boolean \| undefined`	`false`	Public Pimolu prop; see the source declaration for details.
`disabled`	`boolean \| undefined`	`false`	Public Pimolu prop; see the source declaration for details.
`icon`	`ReactNode`	—	Decorative icon displayed before the link label.
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`type`	`string \| undefined`	`"button"`	Standard React/HTML attribute.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`onChange`	`ChangeEventHandler<HTMLAnchorElement, Element> \| undefined`	—	Standard React/HTML attribute.
`onClick`	`MouseEventHandler<HTMLAnchorElement> \| undefined`	—	Standard React/HTML attribute.

active: boolean | undefined
Default: false
Public Pimolu prop; see the source declaration for details.
disabled: boolean | undefined
Default: false
Public Pimolu prop; see the source declaration for details.
icon: ReactNode
No default extracted.
Decorative icon displayed before the link label.
childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
type: string | undefined
Default: "button"
Standard React/HTML attribute.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
onChange: ChangeEventHandler<HTMLAnchorElement, Element> | undefined
No default extracted.
Standard React/HTML attribute.
onClick: MouseEventHandler<HTMLAnchorElement> | undefined
No default extracted.
Standard React/HTML attribute.

PimoluNavbarActionsProps

Type source

PimoluNavbarActionsProps public API
Name	Type	Default	Description
`children`Required	`ReactNode`	—	Public Pimolu prop; see the source declaration for details.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`onChange`	`ChangeEventHandler<HTMLDivElement, Element> \| undefined`	—	Standard React/HTML attribute.
`onClick`	`MouseEventHandler<HTMLDivElement> \| undefined`	—	Standard React/HTML attribute.

childrenRequired: ReactNode
No default extracted.
Public Pimolu prop; see the source declaration for details.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
onChange: ChangeEventHandler<HTMLDivElement, Element> | undefined
No default extracted.
Standard React/HTML attribute.
onClick: MouseEventHandler<HTMLDivElement> | undefined
No default extracted.
Standard React/HTML attribute.

Accessibility

Give navigation a useful accessible name and use real href destinations.
Keep open/close labels clear when replacing the hamburger icon. active items identify the current page.

Read the accessibility guide →

Navbar

Preview

More examples

Surface treatments

Basic

Mobile menu

Usage

API reference

PimoluNavbarProps

PimoluNavbarBrandProps

PimoluNavbarContentProps

PimoluNavbarToggleProps

PimoluNavbarItemProps

PimoluNavbarActionsProps

Accessibility

Preview

More examples

Surface treatments

Basic

Mobile menu

Usage

API reference

PimoluNavbarProps

PimoluNavbarBrandProps

PimoluNavbarContentProps

PimoluNavbarToggleProps

PimoluNavbarItemProps

PimoluNavbarActionsProps

Accessibility

Related components