Navigation patterns help users understand where they are and where they can go next.

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

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.

Screenshot of GitHub with the global navigation bar highlighted

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.

Nav list component guidelines

A nav list component

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.

Tree view component guidelines

A tree view component


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.

Underline nav component guidelines

Underline panel component guidelines

An underline nav component highlighted on a repository page

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.

Action menu component guidelines

Screenshot of '+' action menu expanded in global navigation

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.

Breadcrumbs component guidelines

Screenshot of files page breadcrumb


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.

Pagination component guidelines

Screenshot of issues page pagination

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.

Segmented control component guidelines

Screenshot of code/blame/preview on .md files


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

Screenshot of a repo's security advisories page with the sidebar and main areas highlighted

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

Screenshot of a repo's security advisories page with the tabs and tab panel areas highlighted

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

Wireframe of a settings page with multiple nested 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 (h3h6).

See our typographic style options for heading styles.


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.