Underline nav

The UnderlineNav is used to display navigation.


The underline nav is used to provide navigation links to related views for the user's current context. It is typically used as primary navigation at the top of the page or as secondary or tertiary navigation when nested in views with a nav list.


Anatomy of the UnderlineNav component

  • Item: A navigation link.
  • Current item: The item currently selected is highlighted with an underline.
  • Label: Describes the navigation item.
  • Leading icon (optional): An icon that identifies the navigation item.
  • Counter (optional): Displays a count next to the label.
  • Overflow menu: A disclosure menu that displays additional items when there are too many to fit in the available space.



The underline nav is composed of a list of items. Each item is a link that can be selected to navigate to a different page in the current context.

Label text

The title of the view associated with that tab. Keep labels clear, short, and concise.

Leading icons

Use an Octicon to improve the scannability of common items, but only when relevant. When adding leading icons, all items in the navigation should have one.

Make sure that icons used are consistent across views, and that they are not repeated for different navigations across the product.


You may include a counter to indicate the number of related resources contained in the desitination page, such as the number of open issues.

When loading multiple counters asynchronously, wait for all the data to be ready before displaying the counters, so you can avoid multiple layout shifts. Use the counter loading state while waiting for the data.



The underline nav has two possible main placements depending on its intended usage:

  • As primary navigation: place it at the top of the page. Ensure any secondary and tertiary navigation is nested under the underline nav.
  • As secondary or tertiary navigation: place it above the main content of the page.

In either scenarios, avoid stacking multiple uderline navs to display multiple levels of navigation.


Align the the underline nav to the left and, when possible, make the component span the available width.

Responsive design

The underline nav without overflowing items and the component on a smaller viewport showing the overflow menu

Underline nav handles overflowing items automatically by collapsing them into a disclosure menu. When some of the items don't fit the available space, the component will first hide leading icons to economize space and then move items to the overflow menu one by one.


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.

Keyboard navigation

Items can be activated using a cursor or keyboard

Activates the focused item.
Moves focus to the next item.

Known accessibility issues (GitHub staff only)

View open accessibility issues related to this component