Skip to main contentPrimer

UnderlineNav

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

Page navigation navigation

React
readyReviewed for a11y
Storybook|Source
Rails
readyNot reviewed for a11y
Docs|Lookbook|Source
Figma
View in Figma|

The UnderlineNav 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 UnderlinePanels component.

React examples

Default

Repository navigation

With counter badges

You may include a counter for relevant counts (e.g., open issues) and load them simultaneously to prevent layout shifts.

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

Repository with counters navigation

With leading icons

Use consistent, meaningful icons to aid scannability. Either items in the navigation should have a leading icon or none of the items do.

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

Repository with leading icons navigation

More code examples

The previous examples are a curated subset of the full capabilities (such as reponsive behavior) of the UnderlineNav component. For more examples, see the UnderilneNav Storybook stories

Props

UnderlineNav

NameDefaultDescription
aria-label
string

A unique name for the rendered nav landmark. It will also be used to label the arrow buttons that control the scroll behaviour on coarse pointer devices. (I.e. 'Scroll aria-label left/right')

children Required
UnderlineNav.Item[]
loadingCounters
false
boolean

Whether the navigation items are in loading state. Component waits for all the counters to finish loading to prevent multiple layout shifts.

sx
SystemStyleObject

UnderlineNav.Item

NameDefaultDescription
aria-current
false
| '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.

counter
number | string

The number to display in the counter label.

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 and 'href' is ignored. (Required prop for the react router is 'to' for example)

icon
Component

The leading icon comes before item label

onSelect
(event) => void

The handler that gets called when a nav link is selected. For example, a manual route binding can be done here(I.e. 'navigate(href)' for the react router.)

as
"a"
React.ElementType
sx
SystemStyleObject
See a for more prop options

Related links