App structure

Apps are structured to work seamlessly with the Shopify admin and to provide an intuitive experience for merchants.

An app in the Shopify admin, with numbered indicators for the Shopify admin (1), app nav (2), app header (3), page header (4), overflow menu (5), and app body (6). An app in the Shopify admin, with numbered indicators for the Shopify admin (1), app nav (2), app header (3), page header (4), overflow menu (5), and app body (6).
Switch to desktop view
Switch to mobile view

Anatomy

Anchor link to section titled "Anatomy"
  1. The Shopify admin
  2. App nav
  3. App header
  4. Page header
  5. Overflow menu
  6. App body

Apps consist of a few navigation elements and the app body, which is the center of your app’s experience.

App navigation is strictly configured, and it’s an important part of providing a great merchant experience. For more details, refer to the navigation guidelines.

The app body highlighted within the Shopify admin. The app body highlighted within the Shopify admin.
Switch to desktop view
Switch to mobile view

App body

Anchor link to section titled "App body"

The app body is where your app’s main experience lives.

Be sure to follow the layout guidelines when you choose a layout for the app body.

Full-screen mode

Anchor link to section titled "Full-screen mode"

Full-screen mode is a focused environment for specific immersive tasks.

Full-screen mode utilizes the following areas of the app interface:

  1. FullscreenBar
  2. App body
An empty full-screen app with numbered indicators for the Fullscreen bar (1) and the app body (2). An empty full-screen app with numbered indicators for the Fullscreen bar (1) and the app body (2).
Switch to desktop view
Switch to mobile view

When to use full-screen mode

Anchor link to section titled "When to use full-screen mode"

Use full-screen mode when merchants need to complete a focused task, where leveraging the app’s entire canvas improves the experience.

The following are some use cases for full-screen mode:

  • Complex editing experiences, like an editor for creating newsletter content
  • Immersive experiences, like an editor for cropping and modifying images
  • Previews, like an app that adds elements to a product page and enables merchants to preview changes
The Puzzlify template editor, which is set in full-screen mode, with a Fullscreen bar showing a back button, a ‘New template’ title, and a ‘Save changes’ button.

Behavior

Anchor link to section titled "Behavior"
Full-screen mode launches only after merchants interact with a button that indicates the entire canvas will be used.

Tip

Apps can also enter full-screen mode when merchants follow deep links that include the fullscreen=true URL parameter.
A card in the app body that invites the merchant to ‘Launch the template editor’.

Shopify App Store requirement

Your app can only launch full-screen mode from the app body.
A back button in a full-screen mode Fullscreen bar that sends the merchant back to the previous screen that they were on.

Mandatory

Return merchants to the screen that they were previously on when they exit full-screen mode.
A link in the app nav that opens up a full-screen experience.

Unacceptable

Your app must not launch full-screen mode from the app nav.

FullscreenBar

Anchor link to section titled "Fullscreen bar"

The Polaris FullscreenBar component enables merchants to exit a full-screen interface.

Return merchants to the same screen where they entered full-screen mode.

Info

The mobile FullscreenBar component collapses into the Actions overflow menu when more than two actions are added.
The Puzzlify template editor, a full-screen experience, with the Fullscreen bar ‘back’ button being highlighted. The Puzzlify template editor, a full-screen experience, with the Fullscreen bar ‘back’ button being highlighted.
Switch to desktop view
Switch to mobile view

Mandatory

In full-screen mode, display the FullscreenBar component with a back button.
A dialog box that reads ‘Your template has unsaved changes. Changes will be lost if you leave without saving’ with a primary button with the label ‘Save changes’ and a secondary button with the label ‘Leave without saving’.

Mandatory

If there are unsaved changes, prompt merchants to save before exiting full-screen mode.
A dialog box that reads ‘You’re about to leave the template editor and go back to the Puzzlify home page’ with a primary button with the label ‘Yes, I’m sure’ and a secondary button with the label ‘No, I want to stay’.

Unacceptable

Don’t unnecessarily interrupt a merchant’s workflow when exiting full-screen mode.