Navigation
Navigation patterns help users understand where they are and where they can go next.
Primer Design System
Site navigation
On this page
On this page
This documentation provides an overview of navigation design patterns within Primer. For more granular guidance about the components and insights into their implementation, reference their respective guidelines pages.
Best practices
Prioritize clarity and simplicity to facilitate seamless user interaction.
Clear user orientation
Users should always have a clear understanding of their location within the application. Intuitive navigational cues minimize ambiguity.
Streamlined choices
Minimize the number of navigational elements while ensuring that the most essential items are available. This balance can help prevent users from feeling overwhelmed with too many options, but also ensure that they can easily find what they need.
Contextual transitions
Strive to maintain a balance between contextual clarity and minimal interruption. While transitions such as page refreshes or showing a dialog are useful for indicating context switches, excessive transitions can lead to unnecessary cognitive load.
Contextual shifts and transitions
Entirely new page
This is the default behavior of clicking a link or submitting a form. The URL changes and the requested page loads.
In GitHub's single-page app architecture, this behavior is emulated without a traditional page reload.
If you're navigating from a parent page to a child page, the child page should have a clear way to navigate back to the parent page. This is often done with breadcrumbs or a "back" button.
For example, when adding a new Codespace secret, the user is taken to a new page to fill out the secret details. There is a breadcrumb at the top of the page letting them go back to the Codespace settings page.
Be mindful of data loss when a user is navigating away from a page where they have unsaved changes. See the saving guidelines for more info on handling unsaved changes.
Same page, different state
Example: user activated a different state of their current page.
When using this kind of navigation, strive to avoid full page reloads when feasible. This could help maintain a fast and smooth user experience.
The URL may or may not change.
New spot on the same page
Example: User navigated to a different section or moved focus to a specific element within the same page.
The page content is not changed. This behavior is commonly used for scrolling to new sections or focusing on input fields.
The URL should change if the section scrolled to is a page anchor.
Moving into a dialog
Opening a dialog brings the user into a new context, but can feel "lighter" than going to a whole new page. Focus is moved into the dialog, and the user can't interact with the rest of the page without dismissing the dialog.
The URL may or may not change when opening a dialog.
Patterns and components
Nav list
A vertical list of links that can be used to implement a parent-detail navigation pattern. Users can navigate between different child views without leaving the parent page. It's often used in the sidebar of a split page layout.
Activating a nav list item should change the URL.
Tree view
A tree view isn't semantically a form of navigation: it's for activating an option from a hierarchical list. However, it's often used to implement a parent-detail navigation pattern. It's often used in the sidebar of a split page layout.
Activating a tree view item may or may not change the URL.
Tabs
Tabs allow users to switch between related views within a consistent context, enhancing navigation efficiency and organization.
Use the underline nav component when activating a tab changes the URL.
Use the underline panels component when activating a tab changes the content in the same page or context without changing the URL.
Activating a tab may or may not change the URL, but you can't mix tabs that change the URL with tabs just switch the visible tab panel.
Action menu
An action menu is not semantically a form of navigation: it's for activating an option from a list. However, it may contain some options that open a dialog or change the URL when activated.
Action menus are also used to overflow horizontal navigation elements (such as tabs) when the container is too narrow to display all options inline.
Activating an action menu item may or may not change the URL.
Breadcrumbs
Breadcrumbs show the user where they are using a hierarchical list of links. Going from start to end, each link is one level of hierarchy deeper.
Activating a breadcrumb item should change the URL.
Pagination
Pagination is used to sequentially navigate long collections of content that's been broken into smaller chunks.
Activating a pagination item should change the URL.
Segmented control
While primarily used to make a selection from a short list, segmented controls can be employed as navigational components for filtering, sorting, or viewing content in a different format.
When being used for navigation, activating a segmented control option may or may not change the URL.
Choosing a pattern for tabbed navigation
When designing an interface with tabbed navigation, first reach for underline nav (when clicking the tab changes the URL) or underline panels (when clicking the tab just toggles tab panel visibility).
If these components don't fit your use-case, you may use a segmented control where the segments are links or role="tab".
Layout
Layout is used to structure your content in a way that reflects the hierarchy of the navigation within the app. Navigational elements should be laid out in close proximity to the content they affect.
For example, pagination should go directly below the collection it navigates.
Layouts for navigating in the same context
Parent-detail split page layout
A "parent" sidebar that affects "detail" content. The "parent" navigation remains on screen while the user navigates between different "detail" views.
Tabbed interfaces
Tabbed interfaces enable seamless navigation between different subpages within a unified context. Tabs go directly above the content they affect.
Headings and hierarchical page sections
A page header is the title area at the top of the main content region that shows the user where they are. It may also to contain navigational elements like breadcrumbs or a link to go up a level of hierarchy.
Use section headings to show the user where they are in the context of the page. These headings should be styled to reflect their hierarchy within the page. Page section headings should be marked up with the appropriate heading level (h3–h6).
See our typographic style options for heading styles.
Responsive sidebar navigation patterns
On wide viewports, the sidebar is always visible. The way we show sidebar controls on narrow viewports depends on how the sidebar affects the main content area.
Sidebar as index of links to detail pages
Wide viewports
Narrow viewports
On narrow viewports, the sidebar is not visible if the user is navigated to /{parent}/{detail-page}. To see the detail page links, users must go back to /{parent}.
If the flow only allows users to go one level deep (for example, /{parent}/{detail-page}), show a link to navigate back to the parent route to see the sidebar as an index page.
If the flow allows the user to go deeper than the detail page (for example, {parent}/{detail-page}/{child-route}), use a breadcrumb to allow users to navigate anywhere in the hierarchy. The breadcrumbs may also be visible on wide viewports, but it's not really needed since the user can use the link in the sidebar to go up a level.
You can see examples of this pattern implemented using Primer React components in Storybook:
Sidebar as set of filter options
Wide viewports
Narrow viewports
On narrow viewports, the sidebar is hidden and filter options become items in a menu. Putting the menu options in a menu saves screen real estate without removing them from the page.
You can see examples of this pattern implemented using Primer React components in Storybook:
- PageLayout / Examples / Filters (action menu on narrow)
- PageLayout / Examples / Filters (bottom sheet on narrow)
- PageLayout / Examples / Filters w/ 2 levels (bottom sheet on narrow)
Filter menu
Use an action menu for most cases, but use a bottom sheet dialog if there are too many options to comfortably fit in an action menu. There's no hard guideline on the max number of items for an action menu but you can use 15 as the max if you're unsure.
Menu trigger options
By default, add a new button to the main content area header. Activating this button opens the menu of filter options.
Alternatively, you may use the content area's heading as a trigger to open the menu of filter options when activated. This pattern is useful for keeping the page header clean by repurposing the heading as a control instead of adding another button to the header. The heading text will be the same as the currently selected filter, so this pattern works when the names of the filters describe the page content.
Since the heading will contain a button, it should be perceivable as an interactive element: it should have styles for interative states (hover, focus, and pressed) and a trailing dropdown triangle to differntiate it from plain text.
Sidebar with a mix of detail page links and filter options
Wide viewports
Narrow viewports
This pattern is just a combination of the two previous patterns described in this section.
On narrow viewports, the sidebar is hidden. Filter options become items in a menu, and detail page links are moved to a parent "index" view.
You can see an example of this pattern implemented using Primer React components in Storybook: PageLayout / Examples / Parent-detail + filters (filters as btm sheet on narrow)
Accessibility
Skip links
Facilitate efficient navigation for screen reader users by including skip links to bypass dense redundant content and navigate directly to essential sections.
Example for skipping redundant content: there is a skip link near the global navigation that allows users skip over all the global navigation items and go straight to the main content.
Example for skipping dense content: there is a skip link near the header of a data table that allows users to skip over the large amount of content often rendered in a data table.
Tab order
Users should be able to tab through the navigation elements in a logical order. The tab order should reflect the visual order of the elements.
Scannable headings
A correct heading structure is critical for enabling users to navigate quickly within a page. Headings are by far the most common navigation technique for screen reader users.
Follow our accessibility guidelines for headings.