Skip to content
Primer Design System/React

Primer Design System

Site navigation

On this page

NavList

Use a nav list to render a vertical list of navigation links.
  • Alpha
  • Not reviewed for accessibility
On this page
This documentation is moving to a new home. Please update any link or bookmark that points to this page. The new content can be found here.
import {NavList} from '@primer/react'

Examples

Simple

With leading icons

With other leading visuals

With trailing visuals

With a heading

With aria-label

With groups

With sub-items

If a NavList.Item contains a NavList.SubNav, the NavList.Item will render as a <button> and the as prop and href prop will be ignored.

With nested sub-items

We only allow for up to 4 levels of nested subnavs. If more than 4 levels is required, it's a good sign that the navigation design needs to be rethought.

With a divider

With React Router

import {Link, useMatch, useResolvedPath} from 'react-router-dom'
import {NavList} from '@primer/react'


function NavItem({to, children}) {
  const resolved = useResolvedPath(to)
  const isCurrent = useMatch({path: resolved.pathname, end: true})
  return (
    <NavList.Item as={Link} to={to} aria-current={isCurrent ? 'page' : undefined}>
      {children}
    </NavList.Item>
  )
}


function App() {
  return (
    <NavList>
      <NavItem to="/">Dashboard</NavItem>
      <NavItem to="/pulls">Pull requests</NavItem>
      <NavItem to="/issues">Issues</NavItem>
    </NavList>
  )
}

With Next.js

import {NavList} from '@primer/react'
import {useRouter} from 'next/router'
import Link from 'next/link'
import React from 'react'


function NavItem({href, children}) {
  const router = useRouter()
  const isCurrent = typeof href === 'string' ? router.asPath === href : router.pathname === href.pathname
  return (
    <NavList.Item as={Link} href={href} aria-current={isCurrent ? 'page' : false}>
      {children}
    </NavList.Item>
  )
}


export default function IndexPage() {
  return (
    <NavList>
      <NavItem href="/">Dashboard</NavItem>
      <NavItem href="/pulls">Pull requests</NavItem>
      <NavItem href="/issues">Issues</NavItem>
      <NavItem
        href={{
          pathname: '/[owner]/[repo]',
          query: {owner: 'test', repo: 'test'},
        }}
      >
        Summary
      </NavItem>
    </NavList>
  )
}

Props

NavList

NameTypeDefaultDescription
aria-label
string
aria-labelledby
string
ref
React.RefObject<HTMLElement>
as
React.ElementType
"nav"

The underlying element to render — either a HTML element name or a React component.

sx
SystemStyleObject

NavList.Item

NameTypeDefaultDescription
href
string

The URL that the item navigates to. href is passed to the underlying <a> element. If as is specified, the component may need different props. If the item contains a sub-nav, the item is rendered as a <button> and href is ignored.

aria-current
| 'page' | 'step' | 'location' | 'date' | 'time' | true | false
false

Set aria-current to "page" to indicate that the item represents the current page. Set aria-current to "location" to indicate that the item represents the current location on a page. For more information about aria-current, see MDN.

defaultOpen
boolean

The open state of the item when it is initially rendered if the item has a SubNav.

ref
React.RefObject<HTMLAnchorElement>
as
React.ElementType
"a"

The underlying element to render — either a HTML element name or a React component.

sx
SystemStyleObject
Additional props are passed to the <a> element. See a docs for a list of props accepted by the <a> element.

NavList.LeadingVisual

NameTypeDefaultDescription
sx
SystemStyleObject
ref
React.RefObject<HTMLElement>

A ref to the element rendered by this component.

NavList.TrailingVisual

NameTypeDefaultDescription
sx
SystemStyleObject
ref
React.RefObject<HTMLElement>

A ref to the element rendered by this component.

NavList.SubNav

NameTypeDefaultDescription
sx
SystemStyleObject
ref
React.RefObject<HTMLElement>

A ref to the element rendered by this component.

NavList.Group

NameTypeDefaultDescription
sx
SystemStyleObject
ref
React.RefObject<HTMLElement>

A ref to the element rendered by this component.

NavList.Divider

NameTypeDefaultDescription
sx
SystemStyleObject
ref
React.RefObject<HTMLElement>

A ref to the element rendered by this component.

Status

Alpha

  • Component props and basic example usage of the component are documented on primer.style/react.
  • Component does not have any unnecessary third-party dependencies.
  • Component can adapt to different themes.
  • Component can adapt to different screen sizes.
  • Component has robust unit test coverage (100% where achievable).
  • Component has visual regression coverage of its default and interactive states.
  • Component does not introduce any axe violations.
  • Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Beta

  • Component is used in a production application.
  • Common usage examples are documented on primer.style/react.
  • Common usage examples are documented in storybook stories.
  • Component has been reviewed by a systems designer and any resulting issues have been addressed.
  • Component does not introduce any performance regressions.

Stable

  • Component API has been stable with no breaking changes for at least one month.
  • Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
  • Component has corresponding design guidelines documented in the interface guidelines.
  • Component has corresponding Figma component in the Primer Web library.
  • Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.