NavList

NavList renders a vertical list of navigation links.

Page navigation navigation

React

readyNot reviewed for a11y

Source

Rails

readyReviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

A NavList organizes navigation links for the user's current context and indicates which view they're currently on. It is typically used as a sidebar that changes what is rendered in the main content area.

React examples

Default

<NavList>
  <NavList.Item href="#" aria-current="page">
    Item 1
  </NavList.Item>
  <NavList.Item href="#">Item 2</NavList.Item>
  <NavList.Item href="#">Item 3</NavList.Item>
</NavList>

<NavList>
  <NavList.Item href="#" aria-current="page">
    Item 1
  </NavList.Item>
  <NavList.Item href="#">Item 2</NavList.Item>
  <NavList.Item href="#">Item 3</NavList.Item>
</NavList>

Grouped item sections

Use groups to simplify navigation in long lists. For visual sections without semantically grouping items in a nested ul, use dividers.

<NavList>
  <NavList.Group title="Group 1">
    <NavList.Item aria-current="true" href="#">
      Item 1A
    </NavList.Item>
    <NavList.Item href="#">Item 1B</NavList.Item>
    <NavList.Item href="#">Item 1C</NavList.Item>
  </NavList.Group>
  <NavList.Group title="Group 2">
    <NavList.Item href="#">Item 2A</NavList.Item>
    <NavList.Item href="#">Item 2B</NavList.Item>
    <NavList.Item href="#">Item 2C</NavList.Item>
  </NavList.Group>
</NavList>

<NavList>
  <NavList.Group title="Group 1">
    <NavList.Item aria-current="true" href="#">
      Item 1A
    </NavList.Item>
    <NavList.Item href="#">Item 1B</NavList.Item>
    <NavList.Item href="#">Item 1C</NavList.Item>
  </NavList.Group>
  <NavList.Group title="Group 2">
    <NavList.Item href="#">Item 2A</NavList.Item>
    <NavList.Item href="#">Item 2B</NavList.Item>
    <NavList.Item href="#">Item 2C</NavList.Item>
  </NavList.Group>
</NavList>

Nested subnav items

Top-level items can expand/collapse sub-items. Only the top-level items act as toggles, not links. Use up to 4 nesting levels—reconsider your navigation design if you need more.

Do not replace your NavList with a TreeView to support a deeply nested navigation structure. A TreeView is never an accessible replacement for navigation, as it serves a different purpose and is not recognized as navigation by assistive technologies.

<NavList>
  <NavList.Item href="#" defaultOpen>
    Item 1
    <NavList.SubNav>
      <NavList.Item href="#" aria-current="page">
        Sub item 1
      </NavList.Item>
      <NavList.Item href="#">Sub item 2</NavList.Item>
    </NavList.SubNav>
  </NavList.Item>
  <NavList.Item href="#">Item 2</NavList.Item>
  <NavList.Item href="#">Item 3</NavList.Item>
</NavList>

<NavList>
  <NavList.Item href="#" defaultOpen>
    Item 1
    <NavList.SubNav>
      <NavList.Item href="#" aria-current="page">
        Sub item 1
      </NavList.Item>
      <NavList.Item href="#">Sub item 2</NavList.Item>
    </NavList.SubNav>
  </NavList.Item>
  <NavList.Item href="#">Item 2</NavList.Item>
  <NavList.Item href="#">Item 3</NavList.Item>
</NavList>

Items with leading visuals

Leading visuals are commonly used to show a visual hint for what the item is. For example, an icon or avatar that represents the view being linked to.

<NavList>
  <NavList.Item href="#" aria-current="page">
    <NavList.LeadingVisual>
      <RepoIcon />
    </NavList.LeadingVisual>
    Repos
  </NavList.Item>
  <NavList.Item href="#">
    <NavList.LeadingVisual>
      <PersonIcon />
    </NavList.LeadingVisual>
    People
  </NavList.Item>
  <NavList.Item href="#">
    <NavList.LeadingVisual>
      <FileDirectoryIcon />
    </NavList.LeadingVisual>
    Folders
  </NavList.Item>
</NavList>

<NavList>
  <NavList.Item href="#" aria-current="page">
    <NavList.LeadingVisual>
      <RepoIcon />
    </NavList.LeadingVisual>
    Repos
  </NavList.Item>
  <NavList.Item href="#">
    <NavList.LeadingVisual>
      <PersonIcon />
    </NavList.LeadingVisual>
    People
  </NavList.Item>
  <NavList.Item href="#">
    <NavList.LeadingVisual>
      <FileDirectoryIcon />
    </NavList.LeadingVisual>
    Folders
  </NavList.Item>
</NavList>

Items with trailing visuals

Trailing visuals are commonly used to show auxiliary information about the item. For example, a count of unread notifications on the page.

<NavList>
  <NavList.Item href="#" target="_blank" aria-current="page">
    Item 1
    <NavList.TrailingVisual>
      <LinkExternalIcon />
    </NavList.TrailingVisual>
  </NavList.Item>
  <NavList.Item href="#" target="_blank">
    Item 2
    <NavList.TrailingVisual>
      <LinkExternalIcon />
    </NavList.TrailingVisual>
  </NavList.Item>
  <NavList.Item href="#" target="_blank">
    Item 3
    <NavList.TrailingVisual>
      <LinkExternalIcon />
    </NavList.TrailingVisual>
  </NavList.Item>
</NavList>

<NavList>
  <NavList.Item href="#" target="_blank" aria-current="page">
    Item 1
    <NavList.TrailingVisual>
      <LinkExternalIcon />
    </NavList.TrailingVisual>
  </NavList.Item>
  <NavList.Item href="#" target="_blank">
    Item 2
    <NavList.TrailingVisual>
      <LinkExternalIcon />
    </NavList.TrailingVisual>
  </NavList.Item>
  <NavList.Item href="#" target="_blank">
    Item 3
    <NavList.TrailingVisual>
      <LinkExternalIcon />
    </NavList.TrailingVisual>
  </NavList.Item>
</NavList>

Items with trailing actions

<NavList>
  <NavList.Item href="#" aria-current="page">
    Item 1
    <NavList.TrailingAction
      label="Pin item 1"
      icon={PinIcon}
      onSelect={() => {
        alert('Fake pin Item 1')
      }}
    />
  </NavList.Item>
  <NavList.Item href="#">
    Item 2
    <NavList.TrailingAction
      label="Pin item 2"
      icon={PinIcon}
      onSelect={() => {
        alert('Fake pin Item 2')
      }}
    />
  </NavList.Item>
  <NavList.Item href="#">
    Item 3
    <NavList.TrailingAction
      label="Pin item 3"
      icon={PinIcon}
      onSelect={() => {
        alert('Fake pin Item 3')
      }}
    />
  </NavList.Item>
</NavList>

<NavList>
  <NavList.Item href="#" aria-current="page">
    Item 1
    <NavList.TrailingAction
      label="Pin item 1"
      icon={PinIcon}
      onSelect={() => {
        alert('Fake pin Item 1')
      }}
    />
  </NavList.Item>
  <NavList.Item href="#">
    Item 2
    <NavList.TrailingAction
      label="Pin item 2"
      icon={PinIcon}
      onSelect={() => {
        alert('Fake pin Item 2')
      }}
    />
  </NavList.Item>
  <NavList.Item href="#">
    Item 3
    <NavList.TrailingAction
      label="Pin item 3"
      icon={PinIcon}
      onSelect={() => {
        alert('Fake pin Item 3')
      }}
    />
  </NavList.Item>
</NavList>

Name	Required	Description
aria-label		`string`
aria-labelledby		`string`
ref		`React.RefObject<HTMLElement>`
as		`React.ElementType`
sx		`SystemStyleObject`

NavList.Item

Name	Required	Description
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` 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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current).
defaultOpen		`boolean` The open state of the item when it is initially rendered if the item has a SubNav.
inactiveText		`string` Text to explain why this item is currently inactive and cannot be activated.
ref		`React.RefObject<HTMLAnchorElement>`
as		`React.ElementType`
sx		`SystemStyleObject`

NavList.LeadingVisual

Name	Required	Description
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLElement>`

NavList.TrailingVisual

Name	Required	Description
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLElement>`

NavList.SubNav

Name	Required	Description
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLElement>`

NavList.Group

Name	Required	Description
children	Required	`ReactNode` A related set of NavList.Items
title		`string` The text that gets rendered as the group's heading. Alternatively, you can pass the `NavList.GroupHeading` component as a child of `NavList.Group`. If both `title` and `NavList.GroupHeading` are passed, `NavList.GroupHeading` will be rendered as the heading.
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLElement>`

NavList.GroupHeading

Name	Required	Description
auxiliaryText		`string` Secondary text which provides additional information about a `Group`.
variant		`'subtle' \| 'filled'` Style variations. Usage is discretionary. - `"filled"` - Superimposed on a background, offset from nearby content - `"subtle"` - Relatively less offset from nearby content
visuallyHidden		`boolean`
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLElement>`

NavList.Divider

Name	Required	Description
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLElement>`

NavList.TrailingAction

Name	Required	Description
as		`a \| button` HTML element to render as.
label	Required	`string` Acccessible name for the control.
icon	Required	`string` Octicon to pass into IconButton. When this is not set, TrailingAction renders as a `Button` instead of an `IconButton`.
href		`string` href when the TrailingAction is rendered as a link.

NavList.GroupExpand

Name	Required	Description
label	Required	`string` Acccessible name for the control.
pages		`number` The total number of pages, used to calculate the number of items to show at a given time.
items	Required	`Array<GroupItems>` The NavList.Items to render in the group.
renderItem		`(item: {text: string}) => React.ReactNode` A function that returns a ReactNode to render in the group. If this is not provided, the group will only render the items in the array.
ref		`React.RefObject<HTMLButtonElement>`

NavList

Page navigation navigation

React examples

Default

Grouped item sections

Nested subnav items

Items with leading visuals

Items with trailing visuals

Items with trailing actions

More code examples

Props

NavList

NavList.Item

NavList.LeadingVisual

NavList.TrailingVisual

NavList.SubNav

NavList.Group

NavList.GroupHeading

NavList.Divider

NavList.TrailingAction

NavList.GroupExpand