Skip to main content
Design system

Navigation Menu

A group of text links used for navigating between related pages or individual sections within a page.

Bundle size: 0
Install: 
npm install @washingtonpost/wpds-ui-kit
|Copy
Usage: 
import { NavigationMenu } from "@washingtonpost/wpds-ui-kit"
|Copy
Storybook:  View on Storybook
Source:  View on Github
Primitive:  View their docs

Table of Contents

Anatomy

Note: Image not to scale

  1. Menu link (text label / trigger)
  2. Submenu indicator
  3. Active state (bold)

Options

Orientation

Navigation menu supports both horizontal and vertical layout orientations. In horizontal orientation, menu links are baseline-aligned, ordered from left to right. In vertical orientation, menu links are left-aligned, ordered from top to bottom.

Navigation menu supports one level of sub-navigation.

Behavior

Hover

Menu links change color to $accessible on hover. Submenu links display background color $faint on hover.

Active

Any menu link can be set to active` to indicate the page or section currently in view. Active links are rendered in font-weight bold.

Disabled

A menu (or submenu) link can be set to disabled, according to the user’s current context and relevance of options.

Overflow

For submenus containing a large number of links, define a max-height and set the container to scroll to allow users to access additional items.

Guidance

For primary navigation, the maximum number of menu links recommended is eight (8). If your use case requires more than 8 menu links, re-evaluate your navigation hierarchy to make use of submenus, or consider using a different component.

Accessibility

When navigation menu is in focus, links can be traversed using left, right, up and down arrow keys, or tab / shift+tab. Pressing the enter key executes a click function, which will navigate the user to the selected link. Links containing a submenu can be accessed by focusing the link and pressing space bar to toggle display of the submenu. Pressing the esc key exits the submenu and moves focus back to the parent link / trigger.

API Reference

NavigationMenuRoot

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
orientation
Orientation
----False
dir
Direction
----False
value
string
----False
defaultValue
string
----False
asChild
boolean
----False
onValueChange
(value: string) => void
----False
delayDurationThe duration from when the pointer enters the trigger until the tooltip gets opened. @defaultValue 200
number
----False
skipDelayDurationHow much time a user has to enter another trigger without incurring a delay again. @defaultValue 300
number
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False

NavigationMenuList

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
asChild
boolean
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
{} & { alignContent?: AlignContent | Globals | ScaleValue | Index; alignItems?: AlignItems | Globals | ScaleValue | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False

NavigationMenuItem

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
value
string
----False
asChild
boolean
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False

NavigationMenuLink

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
onSelect
(event: Event) => void
----False
asChild
boolean
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
{} & { alignContent?: AlignContent | Globals | ScaleValue | Index; alignItems?: AlignItems | Globals | ScaleValue | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False
active
boolean
----False

NavigationMenuTrigger

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child
ReactNode
----False
asChild
boolean
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
{} & { alignContent?: AlignContent | Globals | ScaleValue | Index; alignItems?: AlignItems | Globals | ScaleValue | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False

NavigationMenuContent

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
asChild
boolean
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
{} & { alignContent?: AlignContent | Globals | ScaleValue | Index; alignItems?: AlignItems | Globals | ScaleValue | Index; ... 426 more ...; vectorEffect?: VectorEffect | ... 2 more ... | Index; } & ... 7 more ... & { ...; }
----False
disableOutsidePointerEventsWhen `true`, hover/focus/click interactions will be disabled on elements outside the `DismissableLayer`. Users will need to click twice on outside elements to interact with them: once to close the `DismissableLayer`, and again to trigger the element.
boolean
----False
onEscapeKeyDownEvent handler called when the escape key is down. Can be prevented.
(event: KeyboardEvent) => void
----False
onPointerDownOutsideEvent handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.
(event: PointerDownOutsideEvent) => void
----False
onFocusOutsideEvent handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.
(event: FocusOutsideEvent) => void
----False
onInteractOutsideEvent handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented.
(event: PointerDownOutsideEvent | FocusOutsideEvent) => void
----False
forceMountUsed to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
true
----False
referenceElementTrigger dom element used for positioning
HTMLButtonElement
----False
sideThe preferred side of the trigger to render against when open.
"bottom" | "left" | "right" | "top"
 bottom False
alignThe preferred alignment against the anchor.
"center" | "end" | "start"
 start False
popperOptionsPopper options object to pass to internal popper
Omit<Partial<Options>, "modifiers"> & { createPopper?: <TModifier extends Partial<Modifier<any, any>>>(reference: Element | VirtualElement, popper: HTMLElement, options?: Partial<...>) => Instance; modifiers?: readonly Partial<...>[]; }
----False

NavigationMenuSub

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
ReactNode
----False
orientation
Orientation
----False
value
string
----False
defaultValue
string
----False
asChild
boolean
----False
onValueChange
(value: string) => void
----False
cssWPDS provides a css prop for overriding styles easily. It’s like the style attribute, but it supports tokens, media queries, nesting and token-aware values. All WPDS Components include a css prop. Use it to pass in overrides.
CSS
----False
Edit this page on GitHub.
CommunityXTwittergithubGithubyoutubeYoutube