Components menu
  2. components
  3. navigation
  4. navigation

Navigation

The navigation component is used to display the primary navigation in the sidebar of the frame of any non-embedded application. Navigation includes a list of links that merchants use to move between sections of the application.

Examples

Use to present a navigation menu in the frame.

Drag to resize example

Props

children
React.ReactNode
contextControl
React.ReactNode
locationRequired
string
sections
SectionType[]
userMenu
React.ReactNode
onDismiss
() => void

Required components

The navigation component must be passed to the frame component. The mobile version of the navigation component appears in the top bar component.

Best practices

The navigation component must be used within the frame component.

The navigation component should:

  • Contain primary navigation items that perform an action when clicked. Each action should navigate to a URL or trigger another action like a modal overlay.
  • Only use secondary actions for supplementary actions to the primary actions.
  • Provide a non-primary link or action as a secondary action to a section or an item.
  • Group navigation items into sections based on related categories.
  • Use a section title to clarify the category of a section.
  • Use a major icon for item actions.
  • Use a minor icon for secondary actions.
  • Use the provided navigation section component to group navigation items.

Content guidelines

Navigation should:

  • Use sentence case for primary and secondary navigation items

    • Online store

    • Online Store

  • Use as few words as possible to describe each item label

    • Products

    • Products in your store

  • Use all caps for section labels

    • SALES CHANNELS

    • Sales channels

Navigation section

A navigation section groups together related navigation items. Navigation sections can be clarified by a heading. Merchants can use a section to easily find navigation items within a specific category.

Section properties

Prop Type Description
items Item[] A collection of navigation items to be rendered inside the section
icon IconProps['source'] An icon to be displayed next to the section title
title string A string property providing a title for the navigation section
fill boolean A boolean property indicating whether the section should take up all vertical space available
rollup Rollup[] An object determining the collapsing behavior of the navigation section
action Action[] Renders an icon-only action as a supplementary action next to the section title
separator boolean A boolean property indicating whether the section should have a visual separator

Navigation section item

The content of the navigation component consists of navigation items. Each item is a link or action a merchant can take.

Item properties

Prop Type Description
url string A location for the navigation item to navigate to when clicked
matches boolean A boolean property indicating whether the navigation item should respond to a closely matching location property
exactMatch boolean A boolean property indicating whether the navigation item should respond to an exactly matching location property
matchPaths string[] A string property providing a collection of additional paths for the navigation item to respond to
excludePaths string[] A string property providing an explicit collection of paths the navigation item should not respond to
icon IconProps['source'] An icon to be displayed next to the navigation item
iconBody string (deprecated) Pass a string representing an SVG element into the icon prop instead
badge string | null A string property allowing content to be displayed in a badge next to the navigation item
label string A string property allowing content to be displayed as link text in the navigation item
disabled boolean A boolean property indicating whether the navigation item is disabled
new boolean Indicate whether the navigation item is new by adding an indicator dot to the parent and badge to the item (overwritten by the badge prop)
accessibilityLabel string A visually hidden label for screen readers to understand the content of a navigation item
selected boolean A boolean property indicating whether the navigation item is the currently-selected item
subNavigationItems SubNavigationItem[] A collection of navigation items rendered as nested secondary navigation items
secondaryAction SecondaryAction Renders an icon-only action as a supplementary action next to a navigation item
onClick() function A callback function to handle clicking on a navigation item

Navigation section rollup

Rollup allows items in a navigation section to roll up and be revealed when they are of use to the merchant.

Rollup properties

Prop Type Description
after number A number of items after which the navigation section should be collapsed
view string A string property providing content for the section view action
hide string A string property providing content for the section hide action
activePath string A string property representing the current URL of your application

Navigation section action

Action allows a complementary icon-only action to render next to the section title.

Action properties

Prop Type Description
icon IconProps['source'] An icon to be displayed as the content of the action
accessibilityLabel string A visually hidden label for screen readers to understand the content of the action
onClick() function A callback function to handle clicking on the action

Navigation user menu

The user menu component displays the current user’s avatar and name, and actions that are related to the current logged in user. The menu is displayed at the top of the navigation sidebar at small screen sizes. The user menu can display any messages that the current user has available to read.

Deprecation rationale

As of release 3.6.0 Navigation.UserMenu is deprecated in favor of TopBar.UserMenu which will stay visible on mobile.