<HeroSection title="Navigation" lightImage="/assets/apps/design-guidelines/navigation/navigation-intro-2.png" darkImage="/assets/apps/design-guidelines/navigation/navigation-intro-2.png" > Navigation enables merchants to move between sections of your app. </HeroSection> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ### Why is navigation important? Navigation is how merchants move from task to task. A good navigation structure enables merchants to complete tasks easily and without friction. Build your app's navigation around what merchants need to do. Navigation elements display in the following areas: <OrderedList> 1. App nav 1. App header 1. Page header </OrderedList> </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <Image src="/assets/apps/design-guidelines/navigation/navigation-diagram.png" alt="A primary button that's labeled "Upload image" and a secondary button that's labeled "More actions". The secondary button has a dropdown menu with two items, "Export templates" and "Preview all"." radius="base" /> </SectionLayout.Column> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ## Information architecture Information architecture (IA) is the practice of organizing sections so that they make sense as a whole. ### Why is IA important? IA shows merchants where they currently are, and how to navigate the rest of the app. It should be obvious what previously happened and what will happen next. Rely on the relationship between the app nav and app body components to guide merchants where they need to go. Use the fewest possible categories to define what your app does. </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <Image src="/assets/apps/design-guidelines/navigation/ia-intro.png" alt="The Shopify admin with numbered indicators for the app nav (labeled 1), the app header (labeled 2), and the page header (labeled 3)." radius="base" /> </SectionLayout.Column> <ImageCard image="/assets/apps/design-guidelines/navigation/ia-previous-page.png" alt="App pages that are linked together to form a cohesive information architecture. Users can navigate between pages by clicking on links in the app nav and on breadcrumbs." imageLocation="top" padding="small" > Merchants should be able to return to the previous page without using the browser button. To achieve this, your app can provide breadcrumbs or a Back button on the page. </ImageCard> <ImageCard image="/assets/apps/design-guidelines/navigation/ia-no-external-links.png" alt="The title of a page called "Create template" with a breadcrumb to the previous page, which is called "Template"." imageLocation="top" padding="small" > Don't send merchants outside of the Shopify admin for key actions or during primary workflows. </ImageCard> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ### App home The app URL specified in the [Partner Dashboard](https://partners.shopify.com/current/apps) should point to your app homepage. This page is the default view when your app's name is selected in the Shopify admin. If you're building an app that's made entirely of extensions, then a default app home URL and homepage is provided. </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/app-home.png" alt="A dialog card containing a button that's labeled "View free image", with an icon that indicates it sends the user to an external page when clicked." imageLocation="top" padding="small" > Use the app name to point at your app's homepage. This is controlled in the Partner Dashboard, under App Setup > App URL. </ImageCard> <ImageCard image="/assets/apps/design-guidelines/navigation/duplicate-home.png" alt="An app's homepage with the app's name highlighted in the app nav." imageLocation="top" padding="small" > Avoid duplicating the app homepage's URL in your navigation. </ImageCard> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ## App nav The app nav gives merchants a way to move between pages of your app. The app nav is located in the sidebar in the Shopify admin and in the header in Shopify mobile. </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/navigationmenu-app-bridge.png" alt="An app's homepage with a link to the homepage in the app nav." imageLocation="top" padding="small" > If your app has different sections, then use the App Bridge [ui-nav-menu](/docs/api/app-bridge-library/web-components/ui-nav-menu) web component or [NavMenu](/docs/api/app-bridge-library/react-components/navmenu) React component to integrate the sections into the Shopify admin and Shopify mobile navigation. </ImageCard> </SectionLayout.Column> <SectionLayout.Column span={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/navigationmenu-l2-ADG.png" alt="A navigation menu App Bridge component as rendered in the Shopify admin's app nav. The component is showcased next to its code equivalent." imageLocation="top" padding="small" > Use tabs sparingly for secondary navigation purposes when the [ui-nav-menu](/docs/api/app-bridge-library/web-components/ui-nav-menu) isn't sufficient. Clicking a tab should only change the content below it, not above. Tabs should never wrap onto multiple lines. Navigating between tabs shouldn't cause the tabs to change position or move. </ImageCard> </SectionLayout.Column> <ImageCard image="/assets/apps/design-guidelines/navigation/navigationmenu-short-scannable.png" alt="An example of horizontal tabs used for secondary navigation purposes within the embedded app area." imageLocation="top" padding="small" > Make navigation items short and scannable. Use nouns instead of verbs to keep the navigation menu concise. </ImageCard> <ImageCard image="/assets/apps/design-guidelines/navigation/navigationmenu-truncated.png" alt="An app nav with concisely-labeled items like "Templates", "Photos", "Puzzles", and "Examples"." imageLocation="top" padding="small" > When you use more than seven items in the [ui-nav-menu](/docs/api/app-bridge-library/web-components/ui-nav-menu) web component or [NavMenu](/docs/api/app-bridge-library/react-components/navmenu) React component, item seven and above are truncated into a View more button. </ImageCard> <SectionLayout.Column span={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/navigationmenu-replicate-app-body.png" alt="An app nav with so many items that they get truncated into a section called "View more"." imageLocation="top" padding="small" > Avoid replicating the app nav content in the app body, as it results in unnecessary repetition. </ImageCard> </SectionLayout.Column> <SectionLayout.Column span={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/navigationmenu-titlebar-navigation-ADG.png" alt="A card in the app body that replicates app nav links to other pages of the app." imageLocation="top" padding="small" > Avoid placing the main navigation in the page header. This can mislead merchants. The page header is reserved for in-page actions. </ImageCard> </SectionLayout.Column> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ### App name The app name represents a way for merchants to identify your app across multiple touchpoints in the Shopify admin. The app name can be shorter than the [Shopify App Store listing](/apps/store/requirements#1-app-name), so that it fits into the app nav. <HorizontalLine color="base" margin="base" /> <Notice type="info" label="Info"> To change your app name, in the [Partner Dashboard](https://partners.shopify.com) navigate to App setup. </Notice> </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/titlebar-correct-name.png" alt="Buttons being used as navigation links in the page header." imageLocation="top" padding="small" > Keep app names short, with no more than 20 characters. Names beyond 20 characters will be truncated. </ImageCard> <ImageCard image="/assets/apps/design-guidelines/navigation/titlebar-no-descriptions.png" alt="The app name, which reads "Puzzlify" and is entirely visible." imageLocation="top" padding="small" > Avoid putting a description in the app name. Put the description in the [Shopify App Store listing](/apps/store/requirements#1-app-name) instead. </ImageCard> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ### Navigation icon Submit a navigation icon that displays in the app nav. The navigation icon is gray when it's inactive and green when it's active. To learn more about designing your navigation icon, refer to the [visual design guidelines](/apps/design-guidelines/visual-design#icons). <HorizontalLine color="base" margin="base" /> <Notice type="info" label="Info"> To change your navigation icon, navigate to App setup > Embedded app in the [Partner Dashboard](https://partners.shopify.com). </Notice> </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/navicon-similar.png" alt="The app name, which reads "Puzzlify, an easy to use jigsaw puzzle app", but the latter half of the text is truncated by an ellipsis and isn't visible." imageLocation="top" padding="small" > If you're using an SVG icon in the Shopify admin navigation, then it should look similar to your app's App Store icon. It's not mandatory to have an SVG icon. </ImageCard> <ImageCard image="/assets/apps/design-guidelines/navigation/navicon-border-radius.png" alt="An image of PNG and SVG Puzzlify icons. The two icons look similar, though not identical." imageLocation="top" padding="small" > Navigation app icons are cropped with a 4px border radius. You don't need to submit your icon with rounded corners. </ImageCard> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ## App header The app header contains main structural pieces for your app. It's the header that merchants will interact with throughout the entire app experience. The app header contains the following elements: <OrderedList> 1. App icon and name 1. Pinning icon 1. Overflow menu </OrderedList> </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <Image src="/assets/apps/design-guidelines/navigation/app-header.png" alt="A guideline illustrating the icon crop radius." radius="base" /> </SectionLayout.Column> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ### Overflow menu The overflow menu is reserved for additional support information about your app. The overflow menu includes the following content: - About this app - Support At this time, the overflow menu isn't customizable. <HorizontalLine color="base" margin="base" /> <Notice type="info" label="Info"> On mobile, the option to pin the app is collapsed into the overflow menu. </Notice> </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <Image src="/assets/apps/design-guidelines/navigation/overflow-menu.png" alt="The app header, which represents the topmost part of an app. Included in the image are the app icon and app name (labeled 1), the pinning icon (labeled 2), and the overflow menu (labeled 3)." radius="base" /> </SectionLayout.Column> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ## Page header The page header contains titles and actions for a specific page. The page header should, at the very least, contain the page's title. You can optionally add more elements, such as buttons. For examples, refer to the [ui-title-bar](/docs/api/app-bridge-library/web-components/ui-title-bar) web component or [TitleBar](/docs/api/app-bridge-library/react-components/titlebar) React component documentation. </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <ImageCard image="/assets/apps/design-guidelines/navigation/titlebar-app-bridge.png" alt="The app header, which focuses on the overflow menu. There's a visible selection box with links to learn about the app and get support." imageLocation="top" padding="small" > Use App Bridge's [ui-title-bar](/docs/api/app-bridge-library/web-components/ui-title-bar) web component or [TitleBar](/docs/api/app-bridge-library/react-components/titlebar) React component to integrate with the Shopify admin's navigation. This helps your app stay within recommended guidelines. </ImageCard> </SectionLayout.Column> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ### Page title The page title should be short and describe the general purpose of the page. Try to limit each page to a single purpose. Merchants prefer focusing their attention on specific tasks, and splitting their attention might damage the user experience. </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <Image src="/assets/apps/design-guidelines/navigation/page-title.png" alt="The page header with a code block showcasing the App Bridge TitleBar component." radius="base" /> </SectionLayout.Column> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> <Section> <SectionLayout columns={3}> <SectionLayout.Column> ### Primary and secondary actions The primary and secondary buttons in the [ui-title-bar](/docs/api/app-bridge-library/web-components/ui-title-bar) web component or [TitleBar](/docs/api/app-bridge-library/react-components/titlebar) React component initiate a page-specific action. Primary and secondary button labels should have the following attributes: - Clarity and predictability: Merchants should be able to anticipate what will happen when they click a page action. - Action led: Button labels should always lead with a strong verb that encourages action. To provide enough context for merchants, use a \{verb\}+\{noun\} format. </SectionLayout.Column> <SectionLayout.Column span={2}> <SectionLayout columns={2}> <SectionLayout.Column span={2}> <Image src="/assets/apps/design-guidelines/navigation/primary-secondary-actions.png" alt="The page header with the current page title, "Templates" in focus." radius="base" /> </SectionLayout.Column> <ImageCard image="/assets/apps/design-guidelines/navigation/titlebar-predictable-labels.png" alt="The page header with a primary button that's labeled "New templates" and a secondary button that's labeled "Export templates", in focus." imageLocation="top" padding="small" > Offer merchants clear and predictable action labels. </ImageCard> <ImageCard image="/assets/apps/design-guidelines/navigation/titlebar-truncate-actions.png" alt="A primary button that's labeled "New template" and a secondary button that's labeled "Export templates"." imageLocation="top" padding="small" > The [ui-title-bar](/docs/api/app-bridge-library/web-components/ui-title-bar) web component or [TitleBar](/docs/api/app-bridge-library/react-components/titlebar) React component accepts one primary action and multiple secondary actions. When more than one secondary action is present, they're truncated into a More actions dropdown. </ImageCard> </SectionLayout> </SectionLayout.Column> </SectionLayout> </Section> {/* Footer next/previous */} <Section> <Grid> <HorizontalLine color="base" /> <SectionLayout columns={2}> <SectionLayout.Column justify="start"> <IconCard title="Content" image="/assets/apps/design-guidelines/spot-icons/adg-content.png" href="/apps/design-guidelines/content" subtitle="Previous" iconSize="small" iconLocation="left" variant="elevated" padding="small" maxWidth /> </SectionLayout.Column> <SectionLayout.Column justify="end"> <IconCard title="Alerts" image="/assets/apps/design-guidelines/spot-icons/adg-alerts.png" href="/apps/design-guidelines/user-experience/alerts" subtitle="Next" iconSize="small" iconLocation="left" variant="elevated" padding="small" maxWidth /> </SectionLayout.Column> </SectionLayout> <HorizontalLine color="base" /> </Grid> </Section>