App structure
Apps are structured to work seamlessly with the Shopify admin and to provide an intuitive experience for merchants.
- The Shopify admin
- App nav
- App header
- Page header
- Overflow menu
- 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 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:
FullscreenBar- App body
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, 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
Tip
Apps can also enter full-screen mode when merchants follow deep links that include thefullscreen=true URL parameter.
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.
Must Do
Return merchants to the screen that they were previously on when they exit full-screen mode.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 mobileFullscreenBar component collapses into the Actions overflow menu when more than two actions are added.
Must Do
In full-screen mode, display theFullscreenBar component with a 
Must Do
If there are unsaved changes, prompt merchants to save before exiting full-screen mode.
Do Not
Don’t unnecessarily interrupt a merchant’s workflow when exiting full-screen mode.Admin UI extensions New
Anchor link to section titled "Admin UI extensions"Use admin UI extensions to integrate more deeply with the Shopify admin and create seamless merchant workflows.
Choose from the following extensions:
Admin blockDeveloper previewAdmin actionAdmin linkBulk action
Additional admin extensions are available for more specific use cases.
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.App attribution
Anchor link to section titled "App attribution"Shopify will badge all admin UI extensions with the app icon, name, and a link to your app URL.
When to use admin blocks
Anchor link to section titled "When to use admin blocks"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
Must Do
Contents must be less than600px in height, to avoid overly tall app blocks. If necessary, implement pagination to ensure that this requirement is met.
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.
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.
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.
Must Do
When the admin app block has no data, you must return an empty string to the Summary property.When to use admin actions
Anchor link to section titled "When to use admin actions"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.
Must Do
Don't allow action content to exceed1200px and don't use more than two steps of pagination. Otherwise, your app can be difficult to navigate.
When to use admin links and bulk actions
Anchor link to section titled "When to use admin links and bulk actions"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.
Combining extensions
Anchor link to section titled "Combining extensions"Use app actions and blocks together to provide a more focused merchant experience.
Tip
An admin block can trigger an admin action. For more information, refer to the extension custom protocol.
