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. Numbered indicators show the Shopify admin (labeled 1), app nav (labeled 2), app header (labeled 3), page header (labeled 4), overflow menu (labeled 5), and app body (labeled 6). An app in the Shopify admin. Numbered indicators show the Shopify admin (labeled 1), app nav (labeled 2), app header (labeled 3), page header (labeled 4), overflow menu (labeled 5), and app body (labeled 6).
Switch to desktop view
Switch to mobile view
  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

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 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 (labeled 1) and the app body (labeled 2). An empty full-screen app with numbered indicators for the Fullscreen bar (labeled 1) and the app body (labeled 2).
Switch to desktop view
Switch to mobile view

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, such as an editor for creating newsletter content
  • Immersive experiences, such as an editor for cropping and modifying images
  • Previews, such as an app that adds elements to a product page and enables merchants to preview changes
The Puzzlify template editor in full-screen mode, with a Fullscreen bar that has a "Back" button, a "New template" title, and a "Save changes" button.
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 link in the app nav that opens the app in full screen.

Do Not App Store Requirement

Your app must not launch full-screen mode from the app nav. Instead, launch full-screen mode from the app body. This is an app store requirement.
A "Back" button in a full-screen mode Fullscreen bar, which sends merchants back to the previous screen that they were on.

Must Do

Return merchants to the screen that they were previously on when they exit full-screen mode.

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 highlighted. The Puzzlify template editor, a full-screen experience, with the Fullscreen bar "Back" button highlighted.
Switch to desktop view
Switch to mobile view

Must Do

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". There is a primary button that's labeled "Save Changes" and a secondary button that's labeled "Leave without saving".

Must Do

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". There is a primary button that's labeled "Yes, I’m sure" and a secondary button that's labeled "No, I want to stay".

Do Not

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

Use admin UI extensions to integrate more deeply with the Shopify admin and create seamless merchant workflows.

Choose from the following extensions:

  1. Admin block
    Developer preview
  2. Admin action
  3. Admin link
  4. Bulk action

Additional admin extensions are available for more specific use cases.

Admin blocks (labeled 1) live in the body area of the admin. Admin actions (labeled 2) live in the more actions dropdown. And Admin links (labeled 3) also live in the more actions dropdown.
An admin action modal.
The bulk action menu at the bottom of an index page.
An app block card being used for promotion. The block is labeled "Install companion app". There is a secondary button that reads "Install companion app" and another secondary button that reads "Write a review".

Do Not App Store Requirement

The extension can't be used to display promotions or advertisements. This includes promoting your app, related apps, or requesting app reviews. This is an app store requirement.

Shopify will badge all admin UI extensions with the app icon, name, and a link to your app URL.

Hovering over the app attribution indicator reveals the full app name and color logo.
The app attribution component displays your app’s Shopify App Store logo in grayscale by default. When users hover over the logo it displays in full color, along with the full app name. You don't need to mention your app name when you name your extensions.

Developer preview

This feature is in developer preview. Learn more.

Use admin block extensions to offer your app’s functionality or data in the context of a resource detail page. Merchants have the option to add your app block to a page, and arrange it in the page layout.

App blocks can be embedded into Product, Order, or Customer detail pages using these extension targets.

Learn more about admin blocks.

The app blocks card featuring a search input and several apps.
Guidelines indicate the maximum height of an app block.

Must Do

Contents must be less than 600px in height, to avoid overly tall app blocks. If necessary, implement pagination to ensure that this requirement is met.
A simple form with several input fields.

Must Do

Input fields must be visible at all times. If necessary, app blocks should trigger app actions to ensure that this requirement is met.
An example of an app block featuring an empty state and a non-empty state.

Must Do

Your block must have an empty state that informs merchants about what your app block does. For example, it should tell merchants what data will display in the block.
A simple app block form with the Shopify contextual save bar visible. The bar indicates that there are unsaved changes, and includes buttons to discard or save changes.

Tip

Inputs in your block can work with the contextual save bar by using the Form component, which provides merchants with a familiar save and validation experience.
A collapsed app block with a short summary label
If merchants don't need to use an app block on some pages, then they can collapse the card on that specific page. Use the Summary property to provide up to 30 characters of information to merchants about what’s inside the app block. Again, you can’t use app blocks, including the summary property, to promote your app or block functionality.
A collapsed app block with no summary text.

Must Do

When the admin app block has no data, you must return an empty string to the Summary property.

Use admin action extensions to offer merchants quick access to common actions that they might do with your app. Because apps can add an unlimited number of admin actions, use discrete actions for discrete purposes.

App actions can be targeted to these extension targets.

Learn more about admin actions.

Multiple admin actions from the same app in the "More actions" menu.
Apps can have multiple admin action extensions, which display in the More actions menus.
An app block modal with height guidelines overlayed.

Must Do

Don't allow action content to exceed 1200px and don't use more than two steps of pagination. Otherwise, your app can be difficult to navigate.

If your content doesn't fit well within the format of the block or action, then use an admin link or bulk action instead. If an interaction is complex, such as one that requires more screen space, then routing merchants into your app is a better experience.

Examples include a multi-step process, a very long form with multiple dynamic sections, or a complex editor with several columns.

A wireframe of an open "More actions" menu.
Admin links show up in the More actions menus.
A wireframe of a listing page with a floating "More actions" menu at the bottom.
Bulk actions show up in the More actions menu of bulk actions controls.

Use app actions and blocks together to provide a more focused merchant experience.

An abstracted image of an app block triggering an app action.

Tip

An admin block can trigger an admin action. For more information, refer to the extension custom protocol.
An app block and app action with identical content.

Do Not

Don't duplicate the content of your admin blocks and admin actions. Differentiating the functionality and value of your blocks and actions helps merchants understand which extensions to use and when.