Navigation

A navigation organizes an application's structure and content, making it easy to find information and accomplish tasks. Navigation communicates relationships, context, and actions a user can take within an application.

Examples

Default

Grouped

The following example shows two navigation groups, each with a title prop passed into the nav group component. To keep nav groups accessible an aria-label must be passed in if the title prop is not passed in.

Expandable

Expandable third level

Mixed

Horizontal subnav

A flyout should be a Menu component. Press space or right arrow to open a flyout using the keyboard, use the arrow keys to navigate between flyout items, and press escape or left arrow to close a flyout.

Drilldown

Link text

Types

NavSelectClickHandler

The NavItem onClick prop accepts the NavSelectClickHandler type, which is made up of the following argument and return types:

(
  event: React.FormEvent<HTMLInputElement>,
  itemId: number | string,
  groupId: number | string,
  to: string
) => void;

Props

Nav

*required
Name	Type	Default	Description
aria-label	string		Accessible label for the nav when there are multiple navs on the page
children	React.ReactNode		Anything that can be rendered inside of the nav
className	string		Additional classes added to the container
onSelect	( event: React.FormEvent<HTMLInputElement>, selectedItem: { groupId: number \| string; itemId: number \| string; to: string; } ) => void	() => undefined	Callback for updating when item selection changes
onToggle	( event: React.MouseEvent<HTMLButtonElement>, toggledItem: { groupId: number \| string; isExpanded: boolean; } ) => void	() => undefined	Callback for when a list is expanded or collapsed
ouiaId	number \| string		Value to overwrite the randomly generated data-ouia-component-id.
ouiaSafe	boolean	true	Set the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false.
variant	'default' \| 'horizontal' \| 'horizontal-subnav'		For horizontal navs

NavList

*required
Name	Type	Default	Description
Deprecated: ariaLeftScroll	string	'Scroll left'	Please use backScrollAriaLabel. Aria-label for the left scroll button
Deprecated: ariaRightScroll	string	'Scroll right'	Please use forwardScrollAriaLabel. Aria-label for the right scroll button
backScrollAriaLabel	string	'Scroll back'	Aria-label for the back scroll button
children	React.ReactNode		Children nodes
className	string		Additional classes added to the list
forwardScrollAriaLabel	string	'Scroll foward'	Aria-label for the forward scroll button

NavGroup

*required
Name	Type	Default	Description
children	React.ReactNode	null	Anything that can be rendered inside of the group
className	string	''	Additional classes added to the container
id	string	getUniqueId()	Identifier to use for the section aria label
title	string		Title shown for the group

NavItem

*required
Name	Type	Default	Description
children	React.ReactNode		Content rendered inside the nav item.
className	string		Additional classes added to the nav item
component	React.ElementType<any> \| React.ComponentType<any>	'a'	Component used to render NavItems if React.isValidElement(children) is false
flyout	React.ReactElement		Flyout of a nav item. This should be a Menu component. Should not be used if the to prop is defined.
groupId	string \| number \| null	null	Group identifier, will be returned with the onToggle and onSelect callback passed to the Nav component
hasNavLinkWrapperBeta	boolean		Adds a wrapper around the nav link text. Improves the layout when the text is a react node.
isActive	boolean	false	Flag indicating whether the item is active
itemId	string \| number \| null	null	Item identifier, will be returned with the onToggle and onSelect callback passed to the Nav component
onClick	NavSelectClickHandler		Callback for item click
onShowFlyout	() => void		Callback when flyout is opened or closed
ouiaId	number \| string		Value to overwrite the randomly generated data-ouia-component-id.
ouiaSafe	boolean		Set the value of data-ouia-safe. Only set to true when the component is in a static state, i.e. no animations are occurring. At all other times, this value must be false.
preventDefault	boolean	false	If true prevents the default anchor link action to occur. Set to true if you want to handle navigation yourself.
styleChildren	boolean	true	Whether to set className on children when React.isValidElement(children)
to	string		Target navigation link. Should not be used if the flyout prop is defined.
zIndex	number	9999	z-index of the flyout nav item

NavItemSeparator

*required
Name	Type	Default	Description
component	No type info	'li'

NavExpandable

*required
Name	Type	Default	Description
titlerequired	React.ReactNode		Title content shown for the expandable list
buttonProps	any		Additional props added to the NavExpandable <button>
children	React.ReactNode	''	Anything that can be rendered inside of the expandable list
className	string	''	Additional classes added to the container
groupId	string \| number	null	Group identifier, will be returned with the onToggle and onSelect callback passed to the Nav component
id	string	''	Identifier to use for the section aria label
isActive	boolean	false	If true makes the expandable list title active
isExpanded	boolean	false	Boolean to programatically expand or collapse section
onExpand	(event: React.MouseEvent<HTMLButtonElement, MouseEvent>, val: boolean) => void		allow consumer to optionally override this callback and manage expand state externally. if passed will not call Nav's onToggle.
ouiaId	number \| string		Value to overwrite the randomly generated data-ouia-component-id.
srText	string	''	If defined, screen readers will read this text instead of the list title

CSS variables

Expand or collapse column	Selector	Variable	Value

View source on GitHub