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
Global navigation
This is where users can access the most important parts of the app. It's typically a bar that appears at the top of every page.
A global navigation can include direct links and dropdown buttons that reveal menus with more links.
There is no Primer component for global navigation. Use the other Primer components to build a global navigation that suits your needs.
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.
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 with a nav list or tree view that affects "detail" content. The "parent" navigation remains on screen while the user navigates between different "detail" views.
On narrow viewports, the parent list may be stacked above the detail view or turned into an action menu. See the responsive layout guidelines for more info.
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.
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.