Skip to content
Tutorials Center
My learning

Topics

Lesson 45 of 61 ยท Apps, Integrations and Extensibility

App Blocks and App Embeds

Learn how Shopify apps add UI to Online Store 2.0 themes: support @app blocks in your sections, understand app embeds, uninstall cleanup and what merchants see in the editor.

Before Online Store 2.0, installing an app that needed a spot on the storefront often meant the app edited your theme files: it pasted a snippet into product.liquid or a script tag into theme.liquid. When the merchant switched themes or removed the app, those edits stayed behind, or were lost. The modern replacement is theme app extensions. The app ships its own Liquid, CSS and JavaScript, and the theme only provides places where that code may appear.

There are two ways an app appears on a storefront. An app block is a piece of UI that a merchant places inside a section, like a "Reviews" block on a product page. An app embed is a block of code that loads across the whole page, such as a chat bubble or a tracking script. As a theme developer you are responsible for the first kind: your sections must accept app blocks. This lesson shows how, what the merchant sees, and how cleanup works. It targets current Online Store 2.0 themes; app-side details (the extension project, deployment) are summarized in Theme App Extensions and Third-Party Scripts.

Apps and the theme editor run on Shopify, so everything about real app blocks here is read-only. The runnable examples use a stand-in renderer written in JavaScript: it takes a section's schema, a list of installed "apps" and the merchant's choices, and shows what would be rendered. It imitates the visible behavior, not Shopify's engine.

Making a section accept app blocks

A section declares which block types a merchant can add. To allow apps, include the special type @app in its schema:

LIQUID
{% schema %}
{
  "name": "Product information",
  "blocks": [
    { "type": "title", "name": "Title", "limit": 1 },
    { "type": "price", "name": "Price", "limit": 1 },
    { "type": "@app" }
  ]
}
{% endschema %}

@app is not a real block you design. It is a permission: "app blocks may go here". The merchant opens the section in the theme editor, presses Add block, and sees the theme's own blocks plus a list of blocks provided by installed apps. If your schema does not list @app, apps cannot place blocks there, and merchants will ask you why the review app cannot be added. Themes that use theme blocks can also accept @app in their blocks folder rules; see Blocks and Theme Blocks.

Then the section must render the blocks it has. For app blocks the usual pattern is a case statement with a branch for @app:

LIQUID
{%- for block in section.blocks -%}
  {%- case block.type -%}
    {%- when '@app' -%}
      {% render block %}
    {%- when 'title' -%}
      <h1 {{ block.shopify_attributes }}>{{ product.title }}</h1>
    {%- when 'price' -%}
      <div {{ block.shopify_attributes }}>{{ product.price | money }}</div>
  {%- endcase -%}
{%- endfor -%}

{% render block %} is a special use of render: passing a block object asks Shopify to render that app's block file. The app's own Liquid decides what to print. Your section never sees the app's markup. block.shopify_attributes belongs to your own blocks, so the editor can select them; for app blocks the platform handles it.

flowchart LR
    SCH["Section schema<br/>lists @app"] --> ED["Theme editor<br/>Add block shows app blocks"]
    ED --> JSON["Template JSON stores the block<br/>type points to the app"]
    JSON --> R["Section loop:<br/>when '@app' render block"]
    R --> APP["App's block file<br/>renders its own HTML"]

The theme provides the slot; the app provides the content.

How a block renders: a stand-in

The stand-in below keeps three pieces of data: the section schema, the apps that are installed, and the blocks the merchant has placed. It renders a product information section. Try removing @app from the schema (the app blocks become impossible to add) or changing the block order.

JS Rendering theme blocks and app blocks

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Note the last block. The app "uninstalled-widget" is not in the registry, so it renders nothing, yet its entry is still in placedBlocks. That mirrors real life: when an app is removed, its blocks stop rendering, but stale references can remain in the template JSON until someone cleans them up. The registry, the functions and the HTML are inventions for this demo.

App embeds

An app embed is different: it is not placed in a section. It is declared by the app's extension with a target (for example the page head or the end of the body) and appears in the theme editor under App embeds, where the merchant switches it on or off. When on, Shopify adds the app's code to the page through the same mechanism that carries content_for_header, which is one more reason a theme must keep that output in the layout (Layouts and theme.liquid).

Typical embeds: a chat bubble, an announcement script, a consent banner, a loyalty widget, an analytics tag. Things to know:

  • The theme developer does nothing to enable an embed; the layout just needs to be a normal Online Store 2.0 layout.
  • Embeds are global. Their performance cost lands on every page, so review them like any other script (Theme Performance and Core Web Vitals).
  • Merchants can switch them off without touching code, which is a safe way to test whether an app causes a slowdown or a bug.
JS App embeds injected into head and body

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The real platform does not do string replacement like this, and the real output looks different. What carries over is the model: the app declares a target, the merchant toggles it, and the theme code stays untouched.

Uninstalling and cleanup

Clean uninstalls are the main reason app blocks exist:

  • App blocks and embeds stop rendering when the app is uninstalled, because the extension that supplied them is gone. The theme needs no edits. Stale entries may still sit in a template's JSON until a developer or the editor removes them, so occasionally search templates for block types that point to apps that are not installed.
  • Old-style installs that edited theme files do not clean up by themselves. Look in theme.liquid, product sections and assets/ for leftover script tags, snippets with an app's name and {% render 'app-name' %} calls. Remove them in a branch and compare the page before and after.
  • Data left in the store (metafields, metaobjects, tags) usually remains after an uninstall. Whether to delete it depends on what the app documented.

Because an app's code is not yours, do not hide, wrap or modify its output with CSS you cannot test across updates. If an app block clashes with your layout, give it a container and use the app's own appearance settings first.

Designing for merchants

Think about the merchant who opens your section and presses Add block:

  • Give your own block types clear names, since app blocks are listed next to them.
  • Place @app last in the list, so your own blocks appear first.
  • Set limit on blocks where more than one makes no sense, but do not limit @app unless there is a reason.
  • Tell merchants in your documentation which sections accept app blocks. Product, cart and footer sections are the usual places, and a section without @app is a common support question. The editor's side of this is covered in The Theme Editor and How Merchants Use Your Theme.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does adding { "type": "@app" } to a section's blocks array do?

    @app is a permission, not a design. It tells the editor that app blocks may be placed in the section; the app supplies the markup.
  2. 2. What is the main difference between an app block and an app embed?

    A block is positioned by the merchant in a section; an embed is toggled in the App embeds panel and targets the head or body for the whole page.
  3. 3. A review app is uninstalled. What happens to its app block on the product page?

    Because the app's extension is gone, there is nothing to render. The reference in the JSON can linger until cleaned up, so check templates occasionally.
  4. 4. Which code renders an app block inside a section's block loop?

    Rendering the block object asks Shopify to render the app's block file. The section never handles the app's markup itself.

Summary

  • Theme app extensions replaced theme-editing installs: the app ships its code, the theme provides slots.
  • To accept app blocks, list { "type": "@app" } in the section's schema and render the block with {% render block %} in the @app branch.
  • App embeds target the head or body, are toggled by merchants under App embeds, and cost performance on every page.
  • Uninstalling removes rendering of blocks and embeds, but stale JSON entries and old-style leftovers in theme files need manual cleanup.
  • Design for merchants: clear block names, @app last, and documentation of which sections accept app blocks.
  • The renderers in this lesson are stand-ins that show the model, not Shopify's implementation.

Next: Storefront API and Fetching Data from a Theme