NavList

Ready to use


import {NavList} from '@primer/react-brand'

Examples

Groups

Use NavList.Group to organize related navigation items into labelled groups.

Nested disclosure

Add NavList.SubNav to a NavList.Item when an item needs to expand and collapse nested navigation links.

NavList can include up to five levels when a page hierarchy requires it. Use the fewest levels needed; levels one through four can optionally expand or collapse, and level five is reserved for leaf article links.

With visuals

Use leadingVisual and trailingVisual to add icons to the label area. Visuals are additive: they do not replace disclosure triangles, change item sizing, or move the active and inactive row alignment.

Accessibility

Give each NavList a clear aria-label, especially when the page includes more than one navigation landmark.

Use aria-current="page" on the link for the current page. Only apply aria-current to leaf items that navigate somewhere, not to disclosure rows with nested items.

Keep group titles and disclosure labels short and descriptive. Items with NavList.SubNav must include visible label text so people can understand what will expand.

Component props

NavList Required

name	type	required	description
`children`	`ReactNode`	`true`	`NavList.Item` and `NavList.Group` nodes
`aria-label`	`string`	`true`	Accessible label for the navigation landmark
`aria-labelledby`	`string`	`false`	ID of the element that labels the navigation landmark
`className`	`string`	`false`	Sets a custom class on the `nav` element

Forwards all standard HTML attributes for <nav> elements.

NavList.Item Required

name	type	default	required	description
`as`	`'a' \| 'button'`	`'a'`	`false`	Element used for leaf items
`children`	`ReactNode`		`true`	Item label and optional `NavList.SubNav` for nested disclosure
`href`	`string`		`false`	URL for leaf items when rendering as an anchor
`aria-current`	`'page'`, `'step'`, `'location'`, `'date'`, `'time'`, `'true'`, `'false'`		`false`	Marks a leaf item as current
`defaultExpanded`	`boolean`	`false`	`false`	Opens nested `NavList.SubNav` by default
`expanded`	`boolean`		`false`	Controls the nested `NavList.SubNav` expanded state
`onExpandedChange`	`(expanded) => void`		`false`	Called when the nested `NavList.SubNav` expanded state changes
`leadingVisual`	`ReactElement \| Icon`		`false`	Visual rendered before the label
`trailingVisual`	`ReactElement \| Icon`		`false`	Visual rendered after the label
`disabled`	`boolean`	`false`	`false`	Disables the item. Leaf links receive `aria-disabled`; disclosure buttons receive disabled

Forwards props to the rendered leaf link or disclosure button.

NavList.Group

name	type	required	description
`title`	`ReactNode`	`false`	Heading text for the group
`children`	`ReactNode`	`true`	`NavList.Item` nodes
`className`	`string`	`false`	Sets a custom class on the group list item

NavList.SubNav

name	type	default	required	description
`children`	`ReactNode`		`true`	Nested `NavList.Item` nodes
`className`	`string`		`false`	Sets a custom class on the nested `ul`