Underline nav
The underline nav is used to display navigation in a horizontal tabbed format.
On this page
On this page
Usage
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
- 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.
Counters
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.
Hierarchy
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
Subpage tabs
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
Stacking
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
Layout
Placement
Underline nav should be placed directly above the content it affects.
Alignment
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
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.
Accessibility
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
| Key(s) | Description |
|---|---|
| Enter | Activates the focused item. |
| Tab | Moves focus to the next item. |