App blocks for themes
If your section is part of a JSON template, then you should support blocks of type @app. These blocks enable app developers to create blocks for merchants to add app content to their theme without having to directly edit theme code. You can build app blocks using theme app extensions.
Blocks of type @app aren't supported in statically rendered sections.
In the theme editor, merchants can choose to add app blocks to existing sections, or in a new section.
When merchants choose to add the app to a new section, Shopify automatically wraps the app block in a wrapper section called Apps. You can customize this wrapper section by your own apps.liquid section.
To add support for app blocks to your sections and theme blocks, you need take the following steps:
- Add support for app blocks to the schema
- Render the block content
- Ensure that you have valid section settings
Refer to Dawn's main product section for an example implementation of an existing theme section that opts-in to accepting app blocks.
For framework information about app blocks, including the valid schema for app blocks, refer to the theme app extensions framework documentation.
Anchor to Supporting app blocksSupporting app blocks
To allow merchants to add app blocks to a section or a theme block, you need to include a generic block of type @app in the section or block schema.
For example:
Blocks of type @app don't accept the limit parameter. Including this will result in an error.
Anchor to Render app blocksRender app blocks
To render app blocks, the theme block must use the {% content_for 'blocks' %} Liquid tag. This tag handles block rendering, including app blocks.
For example:
Anchor to Render app blocks alongside section-defined blocksRender app blocks alongside section-defined blocks
To render an app block alongside section-defined blocks, you need to check for the appropriate type, and use the following code:
For example:
Anchor to App blocks and section settingsApp blocks and section settings
To prevent ambiguity with autofill settings, sections that support app blocks can include only one resource setting of each type as a section setting. For example, a section might include only one product setting and only one collection setting.
Anchor to App block wrapperApp block wrapper
Merchants can add app blocks to a page in the following ways:
- As a block within the confines of the section that's rendering the block
- In a similar manner to sections, giving them the full width of the page to render content
Because app blocks aren't sections themselves, Shopify wraps these top-level app blocks in a platform-generated apps.liquid wrapper section by default. However, you can override this default wrapper section by creating your own.
Anchor to Shopify wrapper logicShopify wrapper logic
Shopify determines which wrapper to use for these top-level app blocks based on the following logic:
Anchor to Theme-provided ,[object Object], sectionTheme-provided apps.liquid section
apps.liquid section- If your theme includes a section file named
apps.liquid, Shopify uses this section to wrap any top-level app block added by the merchant. - This provides theme developers specific control over how only app blocks are rendered when added directly to a template.
- The
apps.liquidsection schema needs to support blocks of type@appand must include a preset. If either of these is missing, then anApps not supportedorApps section is invaliderror is returned in the theme editor and merchants aren't able to use the section.
Anchor to Theme-provided ,[object Object], sectionTheme-provided _blocks.liquid section
_blocks.liquid section- If
apps.liquiddoes not exist, Shopify looks for a section file named_blocks.liquid. - This section acts as a more generic wrapper, designed to handle both
@appblocks and@themeblocks when added directly to a template. - The
_blocks.liquidsection schema needs to support block types@themeand@app, and must include a preset. If either of these is missing, then an error is returned in the theme editor and merchants aren't able to use the section
Anchor to Platform-generated ,[object Object], sectionPlatform-generated apps.liquid section
apps.liquid section- If neither
apps.liquidnor_blocks.liquidexists in the theme, Shopify falls back to using a default, platform-generatedapps.liquidwrapper to render the top-level app block.
Anchor to App Wrapper ExamplesApp Wrapper Examples
The apps.liquid section schema can't contain the templates schema attribute. This also includes the templates attribute within the enabled_on/disabled_on schema attributes. It's expected that the apps.liquid section is available on all templates.
For example:
/sections/apps.liquid
To enable merchants to control how the app looks inside of an app section, you can add a setting that lets merchants add margins around the app blocks. This helps make the app section margins consistent with your theme's layout.
/sections/apps.liquid
The apps.liquid section isn't a standard theme section. It can't be manually rendered, meaning you can't include it with {% section 'apps' %}, and it won't show up in the theme editor for merchants to add to pages.