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: 66.55 kB
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.

Trigger

Trigger a navigation menu with a call to action, such as a button, link, icon, or other control.

Position

The display position can be defined directionally based on the location of the trigger.

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.

Accessibility

Keyboard controls

A Navigation Menu shows/hides without delay when the trigger is in focus and space/enter is selected on the keyboard. If the Navigation Menu is open and either shift+tab, or tab, is selected on the keyboard it will move focus to the next focusable element. When esc is selected on the keyboard, it will close the Navigation Menu and move the focus to the trigger.

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.

Avoid non-wayfinding content

A navigation menu is primarily reserved for links. It is not meant to communicate significant amounts of freeform or non-wayfinding content; consider a Popover or Tooltip instead.

API Reference

NavigationMenuRoot

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
enum
ReactNode
----False
orientation
enum
Orientation
----False
dir
enum
Direction
----False
value
string
----False
defaultValue
string
----False
asChild
enum
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
enum
ReactNode
----False
asChild
enum
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?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; }
----False

NavigationMenuItem

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
enum
ReactNode
----False
value
string
----False
asChild
enum
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
enum
ReactNode
----False
onSelect
(event: Event) => void
----False
asChild
enum
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?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; }
----False
active
enum
boolean
----False

NavigationMenuTrigger

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child
enum
ReactNode
----False
asChild
enum
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?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 7 more ... & { ...; }
----False

NavigationMenuContent

PropDescriptionTypeDefaultRequired
childrenAny React node may be used as a child to allow for formatting
enum
ReactNode
----False
asChild
enum
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?: Globals | ScaleValue | Index | AlignContent; alignItems?: Globals | ScaleValue | Index | AlignItems; ... 425 more ...; vectorEffect?: Globals | ... 2 more ... | VectorEffect; } & ... 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.
enum
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.
enum
bottom | left | right | top
 bottom False
alignThe preferred alignment against the anchor.
enum
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
enum
ReactNode
----False
orientation
enum
Orientation
----False
value
string
----False
defaultValue
string
----False
asChild
enum
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