--- title: Configure theme app extensions description: Learn about app blocks and app embed blocks for extending themes with apps. source_url: html: >- https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration md: >- https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md --- ExpandOn this page * [File structure](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#file-structure) * [App blocks for themes](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#app-blocks-for-themes) * [App embed blocks](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#app-embed-blocks) * [Conditional app blocks](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#conditional-app-blocks) * [Schema](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#schema) * [Recommendations](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#recommendations) * [File and content size limits](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#file-and-content-size-limits) * [Restrictions](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#restrictions) * [Next steps](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/configuration.md#next-steps) # Configure theme app extensions A theme app extension is a bundle of app blocks, app embed blocks, assets, and snippets. *** ## File structure When you [create a theme app extension](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions/build), Shopify adds the following `theme-app-extension` directory and subdirectories to your app: ## Theme app extension file structure ```file └── extensions └── my-theme-app-extension ├── assets ├── blocks ├── snippets ├── locales ├── package.json └── shopify.extension.toml ``` ```file └── extensions └── my-theme-app-extension ├── assets │ ├── image.jpg │ ├── icon.svg │ ├── app-block.js │ ├── app-block.css │ ├── app-embed-block.js │ └── app-embed-block.css ├── blocks │ ├── app-block.liquid │ └── app-embed-block.liquid ├── snippets │ ├── app-block-snippet.liquid │ └── app-embed-block-snippet.liquid ├── locales | ├── en.default.json | ├── en.default.schema.json | ├── fr.json | └── fr.schema.json ├── package.json └── shopify.extension.toml ``` ##### Newly-generated extension ``` └── extensions └── my-theme-app-extension ├── assets ├── blocks ├── snippets ├── locales ├── package.json └── shopify.extension.toml ``` ##### Populated ``` └── extensions └── my-theme-app-extension ├── assets │ ├── image.jpg │ ├── icon.svg │ ├── app-block.js │ ├── app-block.css │ ├── app-embed-block.js │ └── app-embed-block.css ├── blocks │ ├── app-block.liquid │ └── app-embed-block.liquid ├── snippets │ ├── app-block-snippet.liquid │ └── app-embed-block-snippet.liquid ├── locales | ├── en.default.json | ├── en.default.schema.json | ├── fr.json | └── fr.schema.json ├── package.json └── shopify.extension.toml ``` | Subdirectory | Description | | - | - | | `assets` | Contains CSS, JavaScript, and other static app content that gets injected into themes.Apps can load [assets](https://shopify.dev/docs/storefronts/themes/architecture#assets) using either the `JavaScript` and `stylesheet` [schema attributes](#schema) or from the `asset_url` and `asset_img_url` Liquid URL filters. | | `blocks` | Contains [app blocks for themes](#app-blocks-for-themes) and [app embed block](#app-embed-blocks) Liquid files. | | `snippets` | Contains Liquid [snippet](https://shopify.dev/docs/storefronts/themes/architecture/snippets) files for the theme app extension, which are bits of code that you can reference in other app blocks and app embed blocks. | | `locales` | Contains JSON locale files to host merchant-facing and customer-facing translations. These files are similar to [theme locale files](https://shopify.dev/docs/storefronts/themes/architecture/locales) in their schema and usage. You can include the following file types:- [Schema locale files](https://shopify.dev/docs/storefronts/themes/architecture/locales/schema-locale-files): Contains merchant-facing translations. Use these files to translate the settings that appear in the theme editor. - [Storefront locale files](https://shopify.dev/docs/storefronts/themes/architecture/locales/storefront-locale-files): Contains customer-facing translations. Use these files to translate the text that appears in the storefront when your app block or app embed block is rendered.**Note:** Merchants can't edit the strings in theme app extension storefront locale files. | | `shopify.extension.toml` | A configuration file containing basic app configuration settings, including the extension name and type (`theme`). | *** ## App blocks for themes 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](#examples-of-app-blocks-in-a-theme) app blocks that are added at the section level. Create an app block by setting the `target` in the schema to `section`. 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](https://shopify.dev/docs/storefronts/themes/tools/online-editor). Tip [Build app blocks responsively](https://www.shopify.com/partners/blog/responsive-app-blocks), so that they can adapt to the size of the sections to which they're added. 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. ### App block support in themes For app blocks to function, a theme must contain the following: * [JSON templates](https://shopify.dev/docs/storefronts/themes/architecture/templates/json-templates). * Sections that [support](https://shopify.dev/docs/storefronts/themes/architecture/blocks/app-blocks#supporting-app-blocks) and [render](https://shopify.dev/docs/storefronts/themes/architecture/blocks/app-blocks#render-app-blocks) blocks of type `@app`. Refer to Dawn's [main product section](https://github.com/Shopify/dawn/blob/main/sections/main-product.liquid) for an example implementation. You can [verify](https://shopify.dev/docs/apps/build/online-store/verify-support) whether a theme supports app blocks. ### Example app block The following example creates a `span` element with a `style` attribute. The `style` value (`color: {{ block.settings.color }}`) searches inside of `schema` for a `settings` key, and then searches for a `color` key, which contains the `"default": "#000000"` value. This value then populates the `style` attribute with the default color `#000000`, which renders the `App blocks let you build powerful integrations with online store themes!` text in black. ## Example app block ```liquid App blocks let you build powerful integrations with online store themes. {% render "app_snippet" %} {% schema %} { "name": "Hello World", "target": "section", "enabled_on": { "templates": ["index"] }, "stylesheet": "app.css", "javascript": "app.js", "settings": [ { "label": "Color", "id": "color", "type": "color", "default": "#000000" } ] } {% endschema %} ``` Tip For a more complex example, refer to Shopify's [product reviews app](https://github.com/Shopify/product-reviews-sample-app). ### Examples of app blocks in a theme The following is an example of an app block added to a section: ![An example of an app block added to a section. The section is beside a product image and is for a product star ratings app block.](https://shopify.dev/assets/assets/images/apps/app-block-D_GUOqGb.png) The following is an example of a wrapped app block: ![An example of an app block added as a section and wrapped to span the full width of the page. The section is below product details and is for a customer review comments app block.](https://shopify.dev/assets/assets/images/apps/app-block-fw-BnIc4Lw5.png) ### 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](#autofill) 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 `` and `` closing tags. Create an app embed block by setting the `target` in the schema to either `compliance_head`, `head`, or `body`. App embed blocks with `compliance_head` will be included first and should be used only when necessary, for example in cookie consent banners. 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](#deep-linking), 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 Tip For a more complex example, refer to our [getting started sample code](https://github.com/Shopify/theme-extension-getting-started). ## Example app embed block ```liquid
{{ "kitten.jpg" | asset_url | img_tag }}
{% schema %} { "name": "App Embed", "target": "body", "settings": [] } {% endschema %} ``` ### Example of an app embed block in a theme ![An example of an app embed block injected into a theme's closing HTML body tag. The app provides a floating element on the page and is for a chat bubble app embed block](https://shopify.dev/assets/assets/images/apps/app-embed-block-BwttjuCQ.png) ### 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`](https://shopify.dev/docs/api/admin-graphql/latest/objects/ScriptTag) object. Loading scripts on specific pages minimizes your app's performance impact by limiting it to only the pages where it's needed. *** ## Conditional app blocks You can control the visibility of an app block or app embed block based on a custom condition. For example, you might want to limit content based on plan tier, or geographic location. The condition can be included in the block's [schema](#schema) with the `available_if` attribute, and the state of the condition is stored in an [app-data metafield](https://shopify.dev/docs/apps/build/custom-data/ownership#app-data-metafields). The metafield can be accessed through the Liquid [`app` object](https://shopify.dev/docs/api/liquid/objects/app). Note The app metafield must be a `boolean` type metafield. For example, if you had an app metafield with the namespace of `conditional` and key of `block1`, then you might use the following schema: ## Conditional app block example ```liquid {% schema %} { "name": "Conditional App block", "target": "section", "stylesheet": "app.css", "javascript": "app.js", "available_if": "{{ app.metafields.conditional.block1 }}", "settings": [ { "label": "Colour", "id": "colour", "type": "color", "default": "#000000" } ] } {% endschema %} ``` *** ## Schema The schema for app blocks and app embed blocks is similar to the [theme section schema](https://shopify.dev/docs/storefronts/themes/architecture/sections/section-schema). It supports the following attributes, some of which are unique to app blocks and app embed blocks: | Attribute | Description | Required | | - | - | - | | `name` | 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. | Yes | | `target` | Where the block is located. The possible values are `section`, `head`, `compliance_head`, and `body`.The value for app blocks is `section`. The values for app embed blocks are `head`, `compliance_head`, and `body`. | Yes | | `JavaScript` | A JavaScript file to load from the `assets` subdirectory.If the block is present on the page, then you can load this file automatically by adding a `