Skip to main content

Navigation

Build primary site navigation with links, nested menus, and an optional mobile drawer.

Examples

Breakpoints

Mobile

320px

Mobile Lg

480px

Tablet

640px

Desktop

1024px
nav-demo.tsx
import { Nav } from '@uswds-tailwind/react/nav'
export default function NavDemo() {
return (
<Nav.Root className="@container min-h-16">
<Nav.Trigger type="button">Menu</Nav.Trigger>
<Nav.Backdrop />
<Nav.Positioner>
<Nav.Content aria-label="Primary navigation">
<Nav.CloseTrigger />
<Nav.List>
<Nav.ListItem><Nav.Link href="#services">Services</Nav.Link></Nav.ListItem>
<Nav.ListItem>
<Nav.Dropdown>
<Nav.DropdownTrigger type="button">About <Nav.DropdownIndicator /></Nav.DropdownTrigger>
<Nav.DropdownContent>
<Nav.DropdownItem value="mission"><Nav.DropdownLink href="#mission">Our mission</Nav.DropdownLink></Nav.DropdownItem>
<Nav.DropdownItem value="team"><Nav.DropdownLink href="#team">Our team</Nav.DropdownLink></Nav.DropdownItem>
</Nav.DropdownContent>
</Nav.Dropdown>
</Nav.ListItem>
</Nav.List>
</Nav.Content>
</Nav.Positioner>
</Nav.Root>
)
}

Component API

Root manages the mobile navigation drawer. Put Trigger, Backdrop, and Positioner inside it, with Content inside Positioner. Use List and Link for destinations or Dropdown parts for submenus.

Root<div>

Pass open to control the mobile drawer and forceAction to prevent automatic dismissal.

PropTypeDescription
openbooleanSets the drawer open state. Root does not forward onOpenChange; omit open for an interactive uncontrolled drawer.
forceActionbooleanPrevents automatic dismissal.

Trigger<button>

Opens the mobile drawer.

AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.

Backdrop<div>

Covers the page behind an open mobile drawer.

AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.

Positioner<div>

Positions drawer content on mobile and inline navigation on desktop.

Content<nav>

Contains navigation links.

AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.

CloseTrigger<button>

Closes the mobile drawer.

AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.

List<ul>

Add ListItem children for direct links and nested menus.

ListItem<li>

Wrap one Link or Dropdown.

Uses drawer styling on mobile and inline styling on desktop.

Dropdown<div>

Owns a nested menu.

PropTypeDescription
onOpenChange({ open: boolean }) => voidReceives nested menu state changes.
openbooleanControlled nested menu visibility.
defaultOpenbooleanInitial uncontrolled nested menu visibility.
onItemSelect({ value: string }) => voidReceives an activated nested menu value.

DropdownTrigger<button>

Opens a nested menu.

PropTypeDescription
isCurrentbooleanMarks the trigger as the current section.
AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.
data-currentPresent when currentStyles the current section.

DropdownContent<ul>

Contains nested menu items.

AttributeValuePurpose
data-stateopen | closedStyle the open and closed states.

DropdownItem<li>

Provides one nested menu value.

PropTypeDescription
valuestring (required)Unique item value.

Uses nested-menu link styling at both breakpoints.

DropdownIndicator<div>

Changes its icon when the nested menu opens.