Underline nav

The underline nav is used to display navigation in a horizontal tabbed format.


The underline nav provides navigation links to let users switch between 2 or more related views without leaving their current context.

If you want to use this pattern without any linked items, use the underline panels component.

Best practices

  • Each tab panel should have discrete content with a unique URL, not just different formats to view the same content.
  • One of the tabs should be selected by default when the user loads the page.
  • Avoid overwhelming the user with too many tabs. Instead consider a navigation structure like a nav list that's meant to handle more links.
  • Each view should have enough information so the user can complete their tasks without switching back and forth between tabs.
  • Views should be able to be navigated in any order. This is not a pattern for navigating stepped flows.


Anatomy of the UnderlineNav component

  • Item: Tabs to switch between views when activated.
  • Current item: The item currently selected is highlighted with an underline.
  • Label text: 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.

Label text

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

Do not rely on leading visuals, tooltips, or supplemental descriptions to communicate what the tab represents.


Use label text that clearly communicates what the tab represents.


Don't rely on supplemental content to communicate what the tab represents.

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.

Label text is required. Leading icons are just a "bonus" affordance and should not be the only way to identify the navigation item.


Use leading icons as an enhancement.


Don't exclude label text.


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.


Tabs may be used to switch between content at different levels of hierarchy:

  • subpages within a larger context
  • content panels within a section of a page
A page with three top-level tabs. Then, a placeholder heading and description followed by more tabs to separate subpage content. Top-level tabs are highlighted.

Subpage tabs

A page with three top-level tabs. Then, a placeholder heading and description followed by more tabs to separate subpage content. Inner subpage content tabs are highlighted.

Page content tabs

Avoid more than 2 levels of tab hierarchy. If you need more than 2 levels of hierarchy, consider:

  • rethinking your information architecture
  • removing a layer of hierarchy and putting more content on the page
  • using a nav list for a level of hierarchy


Don't stack multiple underline navs or underline panels directly on top of eachother to convey hierarchical levels of navigation. Instead, consider using a nav list for a higher level of hierarchy.


Limit the levels of tab hierarchy


Don't stack tabs or create deep levels of tab hierarchy



Underline nav should be placed directly above the content it affects.


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

The left and right edges of the underline nav should not extend beyond the width of the content it affects.

Clear beginning and end

It should be clear where the tab-switchable content begins and ends. Use spacing, borders, headings, or other visual cues to make it clear where the tab-switchable content ends.

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

EnterActivates the focused item.
TabMoves focus to the next item.

Known accessibility issues (GitHub staff only)

View open accessibility issues related to this component