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.liquid
section schema needs to support blocks of type@app
and must include a preset. If either of these is missing, then anApps not supported
orApps section is invalid
error 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.liquid
does not exist, Shopify looks for a section file named_blocks.liquid
. - This section acts as a more generic wrapper, designed to handle both
@app
blocks and@theme
blocks when added directly to a template. - The
_blocks.liquid
section schema needs to support block types@theme
and@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.liquid
nor_blocks.liquid
exists in the theme, Shopify falls back to using a default, platform-generatedapps.liquid
wrapper to render the top-level app block.
As app blocks aren't sections themselves, Shopify wraps these full-width app blocks in a platform-generated section by default. However, you can override this default section by creating your own section called apps.liquid
.
The apps.liquid
section schema needs to include a block of type @app
, as well as a preset
. If either of these is missing, then an Apps not supported
or Apps section is invalid
error is returned in the theme editor and merchants aren't able to use the section.
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.