Skip to main content

Navigation Menu

Navigate a website through links and animated shared panels.

Props
Slots

Anatomy#

NavigationMenu [component; slot=root]
├── NavigationMenu.List [part; slot=list]
│   └── NavigationMenu.Item [part; slot=item]
│       └── NavigationMenu.Trigger [part; slot=trigger]
│           └── triggerIcon [slot]
└── NavigationMenu.Content [part; slot=content]
    └── NavigationMenu.Link [part; slot=link]

Usage#

Use NavigationMenu for website destinations, with direct links and expandable link panels. Use DropdownMenu for a menu of actions. Use Tabs for peer panels that stay on the same page.

import { NavigationMenu } from 'moraine'

export function Example() {
  return (
    <NavigationMenu aria-label="Main navigation">
      <NavigationMenu.List>
        <NavigationMenu.Item value="products">
          <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
          <NavigationMenu.Content>
            <NavigationMenu.Link href="/overview" closeOnSelect>
              Overview
            </NavigationMenu.Link>
          </NavigationMenu.Content>
        </NavigationMenu.Item>
        <NavigationMenu.Item>
          <NavigationMenu.Link href="/docs">Documentation</NavigationMenu.Link>
        </NavigationMenu.Item>
      </NavigationMenu.List>
    </NavigationMenu>
  )
}

Combine expandable panels with direct links. Use NavigationMenu.Content for each panel and NavigationMenu.Link for its destinations; a link can also sit directly in a NavigationMenu.Item. active marks the current page with aria-current="page". closeOnSelect defaults to false; enable it to close the panel on activation. A click handler that calls preventDefault() cancels the close. A disabled link loses its href and gets aria-disabled.

<NavigationMenu.Item value="products">
  <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
  <NavigationMenu.Content>
    <NavigationMenu.Link href="/overview" closeOnSelect>
      Overview
    </NavigationMenu.Link>
  </NavigationMenu.Content>
</NavigationMenu.Item>
<NavigationMenu.Item>
  <NavigationMenu.Link href="/docs" active>
    Documentation
  </NavigationMenu.Link>
</NavigationMenu.Item>

The root renders a navigation landmark. Give it an accessible name when the page has several navigation landmarks. This version supports one level of panels.

Controlled state#

Give each item a stable value, then control the open item with value and onValueChange. onValueChange receives the value of the item to open, or undefined to close, and you write it back to value. A value that matches no enabled item with content leaves the menu closed, so disabled or removed items cannot keep a panel open. For uncontrolled state, defaultValue opens an item after hydration. disabled on the root disables every trigger and link and closes the open panel; on an Item it disables only that item’s trigger or direct links.

<NavigationMenu value={value()} onValueChange={setValue} disabled={disabled()}>
  <NavigationMenu.List>
    <NavigationMenu.Item value="account">
      <NavigationMenu.Trigger>Account</NavigationMenu.Trigger>
      <NavigationMenu.Content>...</NavigationMenu.Content>
    </NavigationMenu.Item>
  </NavigationMenu.List>
</NavigationMenu>

Orientation#

Set orientation="vertical" for a vertical list. Use placement="right" to place its panels beside the triggers.

<NavigationMenu aria-label="Docs navigation" orientation="vertical" placement="right">
  <NavigationMenu.List>...</NavigationMenu.List>
</NavigationMenu>

Hover timing and positioning#

Panels open on hover after openDelay (default 50 ms) while no panel is open; hovering another trigger while a panel is open switches immediately, and click or keyboard activation never waits. The open panel closes closeDelay (default 50 ms) after the pointer leaves the menu, and stays open while focus is inside it. placement (default 'bottom'), align (default 'center'), gutter (default 8), shift, flip, and slide position the shared panel relative to the active trigger.

RTL#

Set dir="rtl" on a surrounding container for right-to-left navigation. Arrow keys follow that direction, including the key that opens a panel from a vertical menu.

<div dir="rtl">
  <NavigationMenu aria-label="Main navigation">
    <NavigationMenu.List>...</NavigationMenu.List>
  </NavigationMenu>
</div>

Use linkRender for a router’s link component. Forward the supplied attributes, events, children, object style, and ref to the anchor.

<NavigationMenu.Link linkRender={RouterLink} href="/components/button">
  Button
</NavigationMenu.Link>

Keyboard interaction#

Arrow keys along the list axis move focus without opening a panel. Home and End focus the first and last enabled navigation controls. Enter and Space activate a trigger. ArrowDown opens a horizontal menu and enters its content; ArrowRight does the same for a vertical LTR menu, and ArrowLeft for RTL.

Tab and Shift+Tab preserve the order between the trigger, its portaled content and the following navigation control. Arrow keys and Home/End move between panel links, while inputs retain their editing keys. Escape closes the panel and returns focus to its trigger. Outside click and focus close the panel without taking focus away from the destination.

Examples#

Product and docs header#

Mix a two-column product panel, a shorter guides panel, and a direct Documentation link. Mark the current page with active.

import { NavigationMenu } from 'moraine'

export function Basic() {
  return (
    <div class="pt-4 flex min-h-64 w-full justify-center">
      <NavigationMenu aria-label="Example navigation">
        <NavigationMenu.List>
          <NavigationMenu.Item value="products">
            <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="gap-2 grid w-[min(28rem,calc(100vw-2rem))] sm:grid-cols-2">
                <NavigationMenu.Link href="#overview" closeOnSelect>
                  <span class="font-medium">Overview</span>
                  <span class="text-muted-foreground">Explore the component library.</span>
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#themes" closeOnSelect>
                  <span class="font-medium">Themes</span>
                  <span class="text-muted-foreground">Make the library fit your product.</span>
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#accessibility" closeOnSelect>
                  <span class="font-medium">Accessibility</span>
                  <span class="text-muted-foreground">Keyboard and screen reader support.</span>
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#getting-started" closeOnSelect>
                  <span class="font-medium">Getting started</span>
                  <span class="text-muted-foreground">Install your first component.</span>
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="guides">
            <NavigationMenu.Trigger>Guides</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-48">
                <NavigationMenu.Link href="#installation" closeOnSelect>
                  Installation
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#composition" closeOnSelect>
                  Composition
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#styling" closeOnSelect>
                  Styling
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item>
            <NavigationMenu.Link href="#documentation" active>
              Documentation
            </NavigationMenu.Link>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
    </div>
  )
}

Open the account panel from page state#

Drive the open item with value and onValueChange. Close with null. A disabled Billing item cannot stay open.

import { Button, NavigationMenu } from 'moraine'
import { createSignal } from 'solid-js'

export function Controlled() {
  const [value, setValue] = createSignal<string | undefined>(undefined)
  const [disabled, setDisabled] = createSignal(false)
  return (
    <div class="min-h-56 space-y-4">
      <div class="flex flex-wrap gap-2">
        <Button size="sm" variant="outline" onClick={() => setValue('account')}>
          Open account
        </Button>
        <Button size="sm" variant="outline" onClick={() => setValue(undefined)}>
          Close
        </Button>
        <Button size="sm" variant="outline" onClick={() => setDisabled((value) => !value)}>
          Toggle disabled
        </Button>
      </div>
      <NavigationMenu
        aria-label="Account navigation"
        value={value()}
        onValueChange={setValue}
        disabled={disabled()}
      >
        <NavigationMenu.List>
          <NavigationMenu.Item value="account">
            <NavigationMenu.Trigger>Account</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-48">
                <NavigationMenu.Link href="#profile" closeOnSelect>
                  Profile
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#settings" closeOnSelect>
                  Settings
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="billing" disabled>
            <NavigationMenu.Trigger>Billing</NavigationMenu.Trigger>
            <NavigationMenu.Content>Billing is unavailable.</NavigationMenu.Content>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
      <p class="text-xs text-muted-foreground">Open item: {value() ?? 'none'}</p>
    </div>
  )
}

Vertical docs navigation#

Stack triggers in a vertical list and place panels to the right.

import { NavigationMenu } from 'moraine'

export function Orientation() {
  return (
    <div class="min-h-56 w-full">
      <NavigationMenu aria-label="Vertical navigation" orientation="vertical" placement="right">
        <NavigationMenu.List>
          <NavigationMenu.Item value="products">
            <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-40">
                <NavigationMenu.Link href="#overview" closeOnSelect>
                  Overview
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#features" closeOnSelect>
                  Features
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="resources">
            <NavigationMenu.Trigger>Resources</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-40">
                <NavigationMenu.Link href="#guides" closeOnSelect>
                  Guides
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#support" closeOnSelect>
                  Support
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
    </div>
  )
}

Forward NavigationMenu link props through Solid Router’s A. Keep href on NavigationMenu.Link.

import { A } from '@solidjs/router'
import { NavigationMenu } from 'moraine'
import type { NavigationMenuT } from 'moraine'

const RouterLink = (props: NavigationMenuT.LinkRenderProps) => (
  <A {...props} href={props.href ?? '#'} />
)

export function RouterLinkExample() {
  return (
    <NavigationMenu aria-label="Documentation navigation">
      <NavigationMenu.List>
        <NavigationMenu.Item>
          <NavigationMenu.Link linkRender={RouterLink} href="/components/button">
            Button
          </NavigationMenu.Link>
        </NavigationMenu.Item>
        <NavigationMenu.Item>
          <NavigationMenu.Link linkRender={RouterLink} href="/components/tabs">
            Tabs
          </NavigationMenu.Link>
        </NavigationMenu.Item>
      </NavigationMenu.List>
    </NavigationMenu>
  )
}

Inherit RTL for a product header#

Wrap the menu in dir="rtl". Triggers, panels, and links follow the writing direction without extra props.

import { NavigationMenu } from 'moraine'

export function Rtl() {
  return (
    <div dir="rtl" class="min-h-56 w-full">
      <NavigationMenu aria-label="RTL navigation">
        <NavigationMenu.List>
          <NavigationMenu.Item value="products">
            <NavigationMenu.Trigger>المنتجات</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <div class="w-40">
                <NavigationMenu.Link href="#overview" closeOnSelect>
                  نظرة عامة
                </NavigationMenu.Link>
                <NavigationMenu.Link href="#features" closeOnSelect>
                  الميزات
                </NavigationMenu.Link>
              </div>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
          <NavigationMenu.Item value="resources">
            <NavigationMenu.Trigger>الموارد</NavigationMenu.Trigger>
            <NavigationMenu.Content>
              <NavigationMenu.Link href="#guides" closeOnSelect>
                الأدلة
              </NavigationMenu.Link>
            </NavigationMenu.Content>
          </NavigationMenu.Item>
        </NavigationMenu.List>
      </NavigationMenu>
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-disabled
Slot: navigation-menunavigation-menu-itemnavigation-menu-triggernavigation-menu-link
Description: Present when the component, slot, or item is disabled.
data-orientation
Slot: navigation-menunavigation-menu-listnavigation-menu-content
Description: Stores the rendered orientation (horizontal or vertical).
data-expanded
Slot: navigation-menu-itemnavigation-menu-triggernavigation-menu-trigger-iconnavigation-menu-content
Description: Present when the panel, accordion, or menu is expanded.
data-closed
Slot: navigation-menu-content
Description: Present when disclosure or transition content is closed.
data-active
Slot: navigation-menu-link
Description: Present when the item or trigger is active.

Props#

NavigationMenu#

Renders a <nav> element by default.

Prop

List#

Renders a <ul> element by default.

Prop

Item#

Renders a <li> element by default.

Prop

Trigger#

Renders a <button> element by default.

Prop

Content#

Renders a <div> element by default.

Prop

Renders a <a> element by default.

Prop