NavList.mdx

title	status	description	source
NavList	Draft	Use nav list to render a vertical list of navigation links.	https://github.com/primer/react/tree/main/src/NavList

import {NavList} from '@primer/react/drafts'

Examples

Simple

<NavList>
  <NavList.Item href="/" aria-current="page">
    Home
  </NavList.Item>
  <NavList.Item href="/about">About</NavList.Item>
  <NavList.Item href="/contact">Contact</NavList.Item>
</NavList>

With leading icons

<NavList>
  <NavList.Item href="/" aria-current="page">
    <NavList.LeadingVisual>
      <HomeIcon />
    </NavList.LeadingVisual>
    Dashboard
  </NavList.Item>
  <NavList.Item href="/pulls">
    <NavList.LeadingVisual>
      <GitPullRequestIcon />
    </NavList.LeadingVisual>
    Pull requests
  </NavList.Item>
  <NavList.Item href="/issues">
    <NavList.LeadingVisual>
      <IssueOpenedIcon />
    </NavList.LeadingVisual>
    Issues
  </NavList.Item>
</NavList>

With other leading visuals

<NavList>
  <NavList.Item href="/general" aria-current="page">
    <NavList.LeadingVisual>
      <span aria-hidden>#️⃣</span>
    </NavList.LeadingVisual>
    General
  </NavList.Item>
  <NavList.Item href="/q-a">
    <NavList.LeadingVisual>
      <span aria-hidden>🙏</span>
    </NavList.LeadingVisual>
    Q&A
  </NavList.Item>
  <NavList.Item href="/show-and-tell">
    <NavList.LeadingVisual>
      <span aria-hidden>🙌</span>
    </NavList.LeadingVisual>
    Show and tell
  </NavList.Item>
</NavList>

With trailing visuals

<NavList>
  <NavList.Item href="/inbox" aria-current="page">
    Inbox
    <NavList.TrailingVisual>1,234</NavList.TrailingVisual>
  </NavList.Item>
  <NavList.Item href="/saved">Saved</NavList.Item>
  <NavList.Item href="/done">Done</NavList.Item>
</NavList>

With a heading

<>
  <Heading as="h3" id="workflows-heading" sx={{fontSize: 2}}>
    Workflows
  </Heading>
  <NavList aria-labelledby="workflows-heading">
    <NavList.Item href="/" aria-current="page">
      All workflows
    </NavList.Item>
    <NavList.Item href="/ci">CI</NavList.Item>
    <NavList.Item href="/deploy">Deploy</NavList.Item>
    <NavList.Item href="/release">Release</NavList.Item>
  </NavList>
</>

With aria-label

<NavList aria-label="Security">
  <NavList.Item href="/" aria-current="page">
    Overview
  </NavList.Item>
  <NavList.Item href="/policy">Security policy</NavList.Item>
  <NavList.Item href="/advisories">Security advisories</NavList.Item>
</NavList>

With groups

<NavList>
  <NavList.Group title="Overview">
    <NavList.Item href="/getting-started" aria-current="page">
      Getting started
    </NavList.Item>
  </NavList.Group>
  <NavList.Group title="Components">
    <NavList.Item href="/Avatar">Avatar</NavList.Item>
    <NavList.Item href="/Button">Button</NavList.Item>
    <NavList.Item href="/Label">Label</NavList.Item>
  </NavList.Group>
</NavList>

With sub-items

<NavList>
  <NavList.Item href="/branches">Branches</NavList.Item>
  <NavList.Item href="/tags">Tags</NavList.Item>
  <NavList.Item>
    Actions
    <NavList.SubNav>
      <NavList.Item href="/actions" aria-current="page">
        General
      </NavList.Item>
      <NavList.Item href="/actions/runners">Runners</NavList.Item>
    </NavList.SubNav>
  </NavList.Item>
</NavList>

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 a divider

<NavList>
  <NavList.Item href="/" aria-current="page">
    Dashboard
  </NavList.Item>
  <NavList.Item href="/pulls">Pull requests</NavList.Item>
  <NavList.Item href="/issues">Issues</NavList.Item>
  <NavList.Divider />
  <NavList.Item href="/marketplace">Marketplace</NavList.Item>
  <NavList.Item href="/explore">Explore</NavList.Item>
</NavList>

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' : false}>
      {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 {useRouter} from 'next/router'
import Link from 'next/link'
import {NavList} from '@primer/react'

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

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

Props

NavList

MDN } />

NavList.Item

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. } /> 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. } /> MDN } elementType="a" isPolymorphic refType="HTMLAnchorElement" />

NavList.LeadingVisual

NavList.TrailingVisual

NavList.SubNav

NavList.Group

{/* Should `title` be required? */}

NavList.Divider

Status

<ComponentChecklist items={{ propsDocumented: true, noUnnecessaryDeps: true, adaptsToThemes: true, adaptsToScreenSizes: true, fullTestCoverage: true, usedInProduction: false, usageExamplesDocumented: true, hasStorybookStories: false, designReviewed: false, a11yReviewed: false, stableApi: false, addressedApiFeedback: false, hasDesignGuidelines: false, hasFigmaComponent: false }} />