---
gid: temp
title: App structure
description: Apps are structured to work seamlessly with the Shopify admin and to provide an intuitive experience for merchants.
template: landing_page
---

<HeroSection
  title="App structure"
  lightImage="/assets/apps/design-guidelines/app-structure/app-structure-intro-2.png"
  darkImage="/assets/apps/design-guidelines/app-structure/app-structure-intro-2.png"
>
  Apps are structured to work seamlessly with the Shopify admin and to provide an intuitive experience for merchants.
</HeroSection>


<Section>
  <Image
    src="/assets/apps/design-guidelines/app-structure/app-anatomy.png"
    alt="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)."
    radius="base"
  />
</Section>

<Section noPadding="top" width="narrow">
  ## Anatomy

  <OrderedList>
    1. The Shopify admin
    1. App nav
    1. App header
    1. Page header
    1. Overflow menu
    1. App body
  </OrderedList>

  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](/apps/design-guidelines/navigation).
</Section>

<Section width="narrow">
  <SectionLayout>
    <Image
      src="/assets/apps/design-guidelines/app-structure/app-body.png"
      alt="The app body highlighted within the Shopify admin."
      radius="base"
    />
    <SectionLayout.Column>
      ## App body

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

      Be sure to follow the [layout guidelines](/apps/design-guidelines/layout) when you choose a layout for the app body.
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ## Max modal

      Max modal is a focused environment for specific immersive tasks. Refer to Polaris for [guidance on overlays](https://polaris.shopify.com/components/deprecated/modal#best-practices).

      The modal utilizes the following areas of the app interface:

      <OrderedList>
        1. **Modal header**: The max modal can contain a top bar element to render a primary and a secondary action.
        1. **App body**: The modal body is where you can add all the content for a full-screen experience.
      </OrderedList>
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <Image
        src="/assets/apps/design-guidelines/app-structure/max-modal.png"
        alt="An empty max modal with the modal header at the top and an empty modal body below."
        radius="base"
      />
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ### When to use max modal

      Use max modal when merchants need to complete a focused task, where leveraging the full viewport improves the user experience.

      The following are some example use cases:

      - 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
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <Image
        src="/assets/apps/design-guidelines/app-structure/max-modal-when-to-use.png"
        alt="The Puzzlify template editor in a max modal with a wireframed title bar."
        radius="base"
      />
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ### Behavior

      Max modal launches only after merchants interact with a button that indicates the entire canvas will be used.
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <SectionLayout columns={2}>
        <ImageCard
          image="/assets/apps/design-guidelines/app-structure/max-modal-actions.png"
          alt="A modal header with a secondary button labeled 'Change puzzle template' and a primary button labeled 'Save'."
          imageLocation="top"
          padding="small"
        >
          Primary navigation for the app should be shown in the top bar of the modal and the primary actions should not be duplicated. This applies to developers using the latest version of App Bridge.
        </ImageCard>
        <ImageCard
          image="/assets/apps/design-guidelines/app-structure/save-dialog.png"
          alt="A dialog box that reads &quot;Your template has unsaved changes. Changes will be lost if you leave without saving&quot;. There is a primary button that's labeled &quot;Save Changes&quot; and a secondary button that's labeled &quot;Leave without saving&quot;."
          imageLocation="top"
          padding="small"
        >
          If there are unsaved changes, prompt merchants to save before exiting full-screen mode.
        </ImageCard>
        <ImageCard
          image="/assets/apps/design-guidelines/app-structure/interrupt-dialog.png"
          alt="A modal with the title &quot;Are you sure you want to exit?&quot; and text &quot;You're about to leave the template editor and go back to the Puzzlify home page.&quot;. The modal has a secondary button with the label &quot;No, I want to stay&quot; and a primary button with the label &quot;Yes, I&quot;m sure&quot;."
          imageLocation="top"
          padding="small"
        >
          Avoid unnecessarily interrupting a merchant's workflow when exiting modal.
        </ImageCard>
        <ImageCard
          image="/assets/apps/design-guidelines/app-structure/launch-app-nav.png"
          alt="An image of a link in the Shopify navigation bar launching a full-screen experience."
          imageLocation="top"
          padding="small"
        >
          Your app should not launch full-screen or the max modal from the app nav. Instead, they should launch from the app body. This is an app store requirement.
        </ImageCard>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/no-fullscreen-bar.png"
            alt="A max modal that contains a fullscreen bar."
            imageLocation="top"
            padding="small"
          >
            Avoid using the [FullscreenBar](https://polaris.shopify.com/components/navigation/fullscreen-bar) within a max modal, as it results in redundant mechanisms to dismiss the modal.
          </ImageCard>
        </SectionLayout.Column>
      </SectionLayout>
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ## 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:

      <OrderedList>
        1. `Admin block`
        1. `Admin action`
        1. `Admin link`
        1. `Bulk action`
      </OrderedList>

      [Additional admin extensions](/docs/apps/structure/app-extensions/list) are available for more specific use cases.
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <SectionLayout columns={2}>
        <SectionLayout.Column span={2}>
          <Image
            src="/assets/apps/design-guidelines/app-structure/ui-extension-anatomy.png"
            alt="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."
            radius="base"
          />
        </SectionLayout.Column>
        <Image
          src="/assets/apps/design-guidelines/app-structure/app-action.png"
          alt="An admin action modal."
          radius="base"
        />
        <Image
          src="/assets/apps/design-guidelines/app-structure/app-bulk.png"
          alt="The bulk action menu at the bottom of an index page."
          radius="base"
        />
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/extension-marketing.png"
            alt="An app block card being used for promotion. The block is labeled &quot;Install companion app&quot;. There is a secondary button that reads &quot;Install companion app&quot; and another secondary button that reads &quot;Write a review&quot;."
            imageLocation="top"
            padding="small"
          >
            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.
          </ImageCard>
        </SectionLayout.Column>
      </SectionLayout>
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ### App attribution

      Shopify will badge all admin UI extensions with the app icon, name, and a link to your app URL.
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <SectionLayout columns={2}>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/app-atribution.png"
            alt="Hovering over the app attribution indicator reveals the full app name and color logo."
            imageLocation="top"
            padding="small"
          >
            The app attribution component displays your app's logo and extension name as it displays in the Shopify App Store.
          </ImageCard>
        </SectionLayout.Column>
      </SectionLayout>
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ### When to use admin blocks
      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](/docs/api/admin-extensions/api/extension-targets).

      [Learn more about admin blocks](/docs/apps/admin/admin-actions-and-blocks#admin-blocks).
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <SectionLayout columns={2}>
        <SectionLayout.Column span={2}>
          <Image
            src="/assets/apps/design-guidelines/app-structure/ui-extension-whento.png"
            alt="The app blocks card featuring a search input and several apps."
            radius="base"
          />
        </SectionLayout.Column>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/600px-max.png"
            alt="Guidelines indicate the maximum height of an app block."
            imageLocation="top"
            padding="small"
          >
            Contents should be less than 600px in height, to avoid overly tall app blocks. If necessary, implement pagination to ensure that this requirement is met.
          </ImageCard>
        </SectionLayout.Column>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/input-field.png"
            alt="A simple form with several input fields."
            imageLocation="top"
            padding="small"
          >
            Input fields should be visible at all times. If necessary, app blocks should trigger app actions to ensure that this requirement is met.
          </ImageCard>
        </SectionLayout.Column>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/block-inform.png"
            alt="An example of an app block featuring an empty state and a non-empty state."
            imageLocation="top"
            padding="small"
          >
            Your block should 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.
          </ImageCard>
        </SectionLayout.Column>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/extension-contextualsave.png"
            alt="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."
            imageLocation="top"
            padding="small"
          >
            Inputs in your block can work with the contextual save bar by using the [Form](/docs/api/admin-extensions/components/forms/form) component, which provides merchants with a familiar save and validation experience.
          </ImageCard>
        </SectionLayout.Column>
      </SectionLayout>
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ### 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](/docs/api/admin-extensions/api/extension-targets).

      [Learn more about admin actions](/docs/apps/admin/admin-actions-and-blocks#admin-actions).
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <SectionLayout columns={2}>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/multi-actions.png"
            alt="Multiple admin actions from the same app in the &quot;More actions&quot; menu."
            imageLocation="top"
            padding="small"
          >
            Apps can have multiple admin action extensions, which display in the More actions menus.
          </ImageCard>
        </SectionLayout.Column>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/1200px-max.png"
            alt="An app block modal with height guidelines overlayed."
            imageLocation="top"
            padding="small"
          >
            Avoid action content that exceeds 1200px and avoid using more than two steps of pagination. Otherwise, your app can be difficult to navigate.
          </ImageCard>
        </SectionLayout.Column>
      </SectionLayout>
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ### 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.
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <SectionLayout columns={2}>
        <ImageCard
          image="/assets/apps/design-guidelines/app-structure/more-bulk-moreaction.png"
          alt="A wireframe of an open &quot;More actions&quot; menu."
          imageLocation="top"
          padding="small"
        >
          Admin links show up in the More actions menus.
        </ImageCard>
        <ImageCard
          image="/assets/apps/design-guidelines/app-structure/more-bulk-bulk.png"
          alt="A wireframe of a listing page with a floating &quot;More actions&quot; menu at the bottom."
          imageLocation="top"
          padding="small"
        >
          Bulk actions show up in the More actions menu of bulk actions controls.
        </ImageCard>
      </SectionLayout>
    </SectionLayout.Column>
  </SectionLayout>
</Section>

<Section>
  <SectionLayout columns={3}>
    <SectionLayout.Column>
      ### Combining extensions

      Use app actions and blocks together to provide a more focused merchant experience.
    </SectionLayout.Column>
    <SectionLayout.Column span={2}>
      <SectionLayout columns={2}>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/block-action.png"
            alt="An abstracted image of an app block triggering an app action."
            imageLocation="top"
            padding="small"
          >
            An admin block can trigger an admin action. For more information, refer to the extension [custom protocol](/docs/api/admin-extensions#custom-protocols-extension).
          </ImageCard>
        </SectionLayout.Column>
        <SectionLayout.Column span={2}>
          <ImageCard
            image="/assets/apps/design-guidelines/app-structure/duplicate-info.png"
            alt="An app block and app action with identical content."
            imageLocation="top"
            padding="small"
          >
            Avoid duplicating 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.
          </ImageCard>
        </SectionLayout.Column>
      </SectionLayout>
    </SectionLayout.Column>
  </SectionLayout>
</Section>

{/* Footer next/previous */}
<Section>
  <Grid>
    <HorizontalLine color="base" />
    <SectionLayout columns={2}>
      <SectionLayout.Column justify="start">
        <IconCard
          title="App Design Guidelines"
          subtitle="Previous"
          iconSize="small"
          iconLocation="left"
          variant="elevated"
          image="/assets/apps/design-guidelines/spot-icons/adg-overview.png"
          href="/apps/design-guidelines"
          padding="small"
          maxWidth
        />
      </SectionLayout.Column>
      <SectionLayout.Column justify="end">
        <IconCard
          title="Layout"
          image="/assets/apps/design-guidelines/spot-icons/adg-layout.png"
          href="/apps/design-guidelines/layout"
          subtitle="Next"
          iconSize="small"
          iconLocation="left"
          variant="elevated"
          padding="small"
          maxWidth
        />
      </SectionLayout.Column>
    </SectionLayout>
    <HorizontalLine color="base" />
  </Grid>
</Section>