Theme app extensions framework
A theme app extension is a bundle of app blocks, app embed blocks, assets, and snippets.
When you create a theme app extension, Shopify adds the following
theme-app-extension directory and subdirectories to your app:
||Contains app block and app embed block Liquid files.|
||Contains Liquid snippet files for the theme app extension, which are bits of code you can reference in other app blocks and app embed blocks.|
Apps that inject inline content on a page extend themes using app blocks. Merchants can add app blocks to a compatible theme section, or as wrapped app blocks that are added at the section level. Create an app block by setting the
target in the schema to
By default, themes don't include app blocks after an app is installed. Merchants need to add the app blocks to the theme, from the Apps section of the theme editor.
Use app blocks for the following types of apps:
Apps that you want to automatically point to dynamic sources, such as product reviews apps and star ratings apps.
Apps that merchants might want to reposition on a page.
Apps that should span the full width of a page.
Themes require the following to accept app blocks:
You can verify whether a theme supports app blocks.
Example app block code
Examples of app blocks in a theme
The following is an example of an app block added to a section:
The following is an example of a wrapped app block:
Benefits of app blocks
App blocks are flexible. Merchants can use the theme editor to add, remove, and reorder app blocks at the section level for easy customization.
An app block can use
autofill resource settings to automatically point to dynamic sources and ensure that content remains in sync with its parent section. For example, an app block on the Products page can point to a dynamic source to show data for different products as they display on the page.
App embed blocks
Apps that don't have a UI component, or that add floating or overlaid elements, extend themes using app embed blocks. Shopify renders and injects app embed blocks before HTML
</body> closing tags. Create an app embed block by setting the
target in the schema to either
By default, app embed blocks are deactivated after an app is installed. Merchants need to activate app embed blocks in the theme editor, from Theme Settings > App embeds. However, your app can provide merchants with a deep link, post installation, to activate an app embed block automatically.
Use app embed blocks for the following types of apps:
Apps that provide a floating or overlaid component to a page, such as chat bubble apps and product image badge apps.
Apps that add SEO meta tags, analytics, or tracking pixels.
App embed blocks are supported in vintage and in Online Store 2.0 themes, because they don't rely on sections or JSON templates. However, app embed blocks can't point to dynamic sources, because these blocks only have access to the Global Liquid scope for the page on which they're rendered.
Example app embed block code
Example of an app embed block in a theme
Benefits of app embed blocks
App embed blocks are supported in vintage and Online Store 2.0 themes. This means any merchant can use your app without you needing to maintain two installation paths: one for vintage themes and one for Online Store 2.0 themes.
After installation, merchants can use the theme code editor to configure app embed block settings for a more customized experience.
App embed blocks allow you to only load scripts on specific pages, which isn't possible with the
ScriptTag REST Admin API or GraphQL Admin API resource. Loading scripts on specific pages minimizes your app's performance impact by limiting it to only the pages where it's needed.
The schema for app blocks and app embed blocks is similar to the theme section schema. It supports the following attributes, some of which are unique to app blocks and app embed blocks:
||The title in the theme editor for the app block or app embed block.
Keep app block and app embed block names under 25 characters so they fit in the theme editor sidebar.
Don't include the title of your app in the name of the block. The title of your app displays below the name of the app block or app embed block in app block pickers, the app embeds panel, and the app details panel.
Where the block is located. The possible values are
The value for app blocks is
If the block is present on the page, then you can load this file automatically by adding a
A CSS file to load from the
If the block is present on the page, then you can load this file automatically by adding a
The templates on which a block is rendered. If not set, then Shopify defaults to all supported templates.
Refer to request.page_type for a list of valid template types.
App blocks and app embed blocks can't be rendered on checkout step pages.
Additional CSS classes to be included in the wrapping tag element, similar to theme section classes.
Theme app extensions will always include the
If set, then a tag wraps the block's output. If not set, then the output is wrapped in a
Settings that you provide to the merchant for customizing the app block or app embed block. These settings appear in the theme editor when the block is selected. Setting values can be accessed using the settings Liquid object.
A default setting configuration for the block. Refer to the section schema for an example.
A set of translated strings for the block. Refer to the section schema for an example and to learn how to access the translation values.
Review the following recommendations for building theme app extensions:
autofill is an app block setting that's automatically set to dynamic sources when merchants add an app block to a section.
App blocks can include settings in the
settings schema object, like sections do. You can give settings that reference resources an additional
autofill indicates that Shopify will determine the setting value automatically when merchants add the app block to a section.
autofill setting values will be set to one of the following sources:
A dynamic source pointing to the parent section's resource setting of the same type.
A dynamic source pointing to the template's global resource.
A featured product section will have a setting of type
product, which allows a merchant to choose which product to display as featured. An app block that has a
product setting with
autofill set will automatically use the featured product.
In the following example,
block.settings.product will use the section's
Simplified installation flow with deep linking
Post-installation, your app can prompt merchants with deep links. When clicked, deep links activate app embed blocks in the theme editor for merchants to preview and adjust before saving and publishing. Deep linking simplifies your app's installation flow, because merchants won't need to navigate to the theme editor, find the block, and then act on it. Instead, your app does the work for them. Because merchants can preview the block, you're providing them with control over what they include in their storefront.
Your app needs to redirect merchants to the following URL, with URL query parameters populated:
URL query parameters
The name of the merchant's shop.
The context in which the app is being activated. The value is
The templates on which a block is rendered. If not set, then Shopify will default to the index template.
The possible values are
The theme app extension.
The filename of the block's Liquid file.
For example, if the Liquid file is located at
To see this Liquid file in the context of an app embed block, refer to the theme app extension getting started sample code.
Lifecycle management and versioning
Use the Partner Dashboard to manage your theme app extension's lifecycle.
extension push command pushes app updates to draft versions on your development store. You can test your theme app extension in a sandbox environment before publishing to online stores.
For example, verify that:
App embed blocks for floating components are positioned properly without obscuring page content.
You can use the theme editor to activate and deactivate app embed blocks and configure their settings.
You can use the theme editor to add, remove, and reposition app blocks and configure their settings.
App documentation, such as app onboarding instructions, is clear, accurate, and complete. To learn more about writing effective help documentation, refer to Help documentation in Shopify Polaris.
When you're ready, you can deploy your app to all the online stores that use it. When you publish a new version of your app, it might take up to five minutes for merchants using the app to be upgraded to the new version.
All files inside the
assets/ folder are automatically served from Shopify's CDN for fast, reliable asset delivery. Reference your assets by using either the
stylesheet schema attributes or using the
asset_img_url Liquid URL filters.
For app embed blocks, take advantage of their ability to only load scripts on specific pages.
Theme editor compatibility
File and content size limits
Shopify validates theme app extensions when you push to a draft extension version and create a version. If the app's content exceeds enforced limits, then the theme app extension will fail validation and won't update.
The following table provides the enforced, and suggested, limits on theme app extensions:
|App content||Limit||Enforced or suggested|
|All files in a theme app extension||10 MB||Enforced|
|Number of blocks||25||Enforced|
|Size of Liquid across all blocks||100 KB||Enforced|
|Size of CSS (compressed) referenced directly by the schema||100 KB||Suggested|
|Size of JS (compressed) referenced directly by the schema||10 KB||Suggested|
The following pages and objects can't be used with theme app extensions.
Theme app extension app blocks and app embed blocks can't be rendered on checkout pages. This includes all pages that are rendered when a customer initiates a checkout, such as Contact information, Shipping method, Payment method, and Order status.
Theme app extensions don't have access to the following Liquid objects:
- Get started building a theme app extension.