Shopify App Blocks vs Theme Sections: When to Use Each

They Look the Same in the Theme Editor — But They're Fundamentally Different

Open the Shopify theme editor, click "Add block" or "Add section," and you'll see a mix of options that all look like the same thing. But behind the interface, app blocks, theme blocks, and sections have different architectures, different capabilities, and different implications for your store's performance, maintainability, and upgrade path.

Understanding the difference between Shopify app blocks vs theme sections matters whether you're a merchant deciding how to add functionality, a developer building a theme, or an app developer creating extensions. The wrong architectural choice leads to brittle themes, leftover code from uninstalled apps, and performance issues that are hard to diagnose.

This guide breaks down exactly what each component is, when to use it, and the architectural decisions that keep your Shopify development clean. If you've ever wondered why some apps integrate cleanly while others inject mysterious code into your theme, this is why.

The Three Types of Building Blocks in Online Store 2.0

Online Store 2.0 introduced a modular architecture with three distinct component types. Each has a different source, different lifecycle, and different editing experience.

Sections

What they are: Self-contained page modules defined in your theme's sections/ folder. Each section is a Liquid file with HTML/CSS/JS at the top and a {% schema %} at the bottom defining settings and blocks.

Who creates them: Theme developers.

Where they live: In the theme's codebase (sections/ folder).

Key characteristics:

• Render as top-level page modules
• Have their own settings panel in the theme editor
• Can contain blocks (both theme blocks and app blocks)
• Up to 25 sections per JSON template
• Persist when you switch themes (if the new theme has a section with the same type name)

Theme Blocks

What they are: Reusable content units that live inside sections. Come in two varieties:

1. Section blocks — defined inside a section's {% schema %} blocks array. Only usable in that specific section.
2. Theme blocks — defined as separate Liquid files in the blocks/ folder. Reusable across any section that accepts them.

Who creates them: Theme developers.

Where they live: Either inline in a section's schema (section blocks) or in the theme's blocks/ folder (theme blocks).

App Blocks

What they are: UI components provided by installed Shopify apps that can be placed into sections or templates through the theme editor — without touching theme code.

Who creates them: App developers (via theme app extensions).

Where they live: In the app's codebase, delivered to the theme through Shopify's app extension system. They do NOT modify your theme files.

Key characteristics:

• Installed/removed with zero theme code changes
• Can be positioned alongside theme blocks in sections
• Can also be added as standalone sections in templates
• Settings configurable through the theme editor
• Clean uninstall — removing the app removes the block completely

According to Shopify's official blocks documentation, theme blocks in the /blocks folder are the newest addition — introduced to reduce code duplication across sections that share the same block types.

When to Use Sections vs Blocks: The Architecture Decision

The most common mistake is treating sections and blocks as interchangeable. They solve different problems.

Use Sections When:

• The content is a standalone page module (hero banner, featured collection, newsletter signup)
• The module needs its own distinct visual boundary on the page
• The module has complex internal structure that wouldn't make sense as a repeatable unit
• You need more than 50 blocks of content (sections have their own 50-block limit)
• The module appears independently on different page types

Use Blocks When:

• The content is a repeatable unit inside a section (individual FAQ items, testimonial cards, feature grid items)
• Merchants need to add, remove, and reorder individual items
• The same block type is needed across multiple sections (use theme blocks)
• The content is a small, composable piece (a text block, an image, a button)

Real-World Examples

For deeper patterns on building sections and blocks, our guide to building custom Shopify sections covers the full implementation with code examples.

App Blocks: The Clean Integration Pattern

Before Online Store 2.0, apps added functionality by injecting code directly into your theme files — modifying theme.liquid, product templates, and other files. This created three persistent problems:

1. Leftover code — uninstalling an app didn't remove its injected code
2. Theme update conflicts — app code injections conflicted with theme updates
3. Performance opacity — you couldn't easily identify which app added which script

App blocks solve all three problems.

How App Blocks Work

App developers define their UI in a theme app extension:

{%- comment -%} Example: reviews app block {%- endcomment -%}
{% schema %}
{
  "name": "Product Reviews",
  "target": "section",
  "settings": [
    {
      "type": "range",
      "id": "reviews_per_page",
      "min": 3,
      "max": 20,
      "default": 5,
      "label": "Reviews to show"
    },
    {
      "type": "checkbox",
      "id": "show_rating_summary",
      "default": true,
      "label": "Show rating summary"
    }
  ]
}
{% endschema %}

<div class="app-reviews-widget" data-limit="{{ block.settings.reviews_per_page }}">
  {%- if block.settings.show_rating_summary -%}
    <div class="reviews-summary">
      {%- comment -%} App renders review summary here {%- endcomment -%}
    </div>
  {%- endif -%}
  <div class="reviews-list">
    {%- comment -%} App renders individual reviews here {%- endcomment -%}
  </div>
</div>

For Theme Developers: Supporting App Blocks

To make your section accept app blocks, add "@app" to the blocks array in your section schema:

{
  "name": "Product Information",
  "blocks": [
    {
      "type": "title",
      "name": "Product Title",
      "limit": 1
    },
    {
      "type": "price",
      "name": "Price",
      "limit": 1
    },
    {
      "type": "@app"
    }
  ]
}

The "@app" type tells Shopify's theme editor to show installed app blocks as available options within this section. Without it, app blocks can only be added as standalone sections — not positioned alongside your theme content.

Should Every Section Accept App Blocks?

No. Shopify's best practices documentation advises considering these questions before adding "@app" support:

• Would the layout break with unexpected block types inserted?
• Would it require edge-case CSS to handle app blocks of varying sizes?
• Would it make the section's purpose vague? A hero banner accepting a reviews widget doesn't make sense.

Add "@app" to sections where third-party functionality adds value — product pages, cart, and collection pages. Skip it for sections with rigid layouts like headers, footers, and hero banners.

Theme Blocks: The Reusability Pattern

Theme blocks (files in the /blocks folder) were introduced to solve code duplication. Before theme blocks, if you wanted a "text with icon" pattern in three different sections, you'd copy the block definition into each section's schema — tripling the code and maintenance burden.

Creating a Theme Block

Create blocks/text-with-icon.liquid:

<div class="text-icon-block" {{ block.shopify_attributes }}>
  {%- if block.settings.icon -%}
    <img
      src="{{ block.settings.icon | image_url: width: 96 }}"
      alt=""
      width="48"
      height="48"
      loading="lazy"
    >
  {%- endif -%}
  {%- if block.settings.heading != blank -%}
    <h3>{{ block.settings.heading }}</h3>
  {%- endif -%}
  {%- if block.settings.text != blank -%}
    <p>{{ block.settings.text }}</p>
  {%- endif -%}
</div>

{% schema %}
{
  "name": "Text with Icon",
  "settings": [
    {
      "type": "image_picker",
      "id": "icon",
      "label": "Icon"
    },
    {
      "type": "text",
      "id": "heading",
      "label": "Heading"
    },
    {
      "type": "textarea",
      "id": "text",
      "label": "Text"
    }
  ]
}
{% endschema %}

Using Theme Blocks in Sections

Reference theme blocks in your section's schema using the "@theme" type:

{
  "name": "Feature Grid",
  "blocks": [
    { "type": "@theme" },
    { "type": "@app" }
  ]
}

"@theme" tells the theme editor to show all compatible theme blocks from the /blocks folder. This means any new theme block you create automatically becomes available in every section that uses "@theme" — no section updates needed.

For projects that need apps and integrations to coexist cleanly with theme content, combining "@theme" and "@app" in the same section gives merchants maximum flexibility.

Performance Implications of Each Approach

Every architectural choice impacts performance. Here's how:

Sections

Each section loads its own CSS and can load its own JavaScript. Shopify's best practice is to only load section assets when the section is present on the page:

{{ 'section-hero.css' | asset_url | stylesheet_tag }}

Performance cost: Minimal — assets are scoped and conditionally loaded.

Theme Blocks

Blocks render within their parent section. Their CSS/JS should be bundled with the section or loaded conditionally:

{%- for block in section.blocks -%}
  {%- case block.type -%}
    {%- when 'video' -%}
      {{ 'block-video.css' | asset_url | stylesheet_tag }}
  {%- endcase -%}
{%- endfor -%}

Performance cost: Minimal when properly scoped. Risk of loading unused assets if not conditionally included.

App Blocks

App blocks load their own JavaScript and CSS — delivered through Shopify's app extension system. Each installed app with a theme extension adds its assets to the page.

Performance cost: Variable and harder to control. A well-built app block adds minimal overhead. A poorly built one can inject hundreds of KB of JavaScript.

For merchants tracking analytics and performance, Shopify's speed dashboard shows the impact of each app embed — use it to identify which app blocks cost the most performance.

Migration: Moving From Legacy Apps to App Blocks

If your theme still has legacy app code injected directly into theme files (ScriptTags, code snippets in theme.liquid), migrating to app blocks is one of the best performance and maintainability investments you can make.

How to Identify Legacy App Code

1. Go to Online Store → Themes → Edit code
2. Open layout/theme.liquid
3. Search for comments like <!-- BEGIN app-name --> or <script> tags referencing external domains
4. Check snippets/ for files you didn't create (often named after apps)

The Migration Process

1. Document what each legacy app code block does — what functionality does it provide?
2. Check if the app now supports app blocks — most modern apps have migrated
3. Remove legacy code from theme files
4. Enable the app's theme extension in Online Store → Themes → Customize → App embeds
5. Add app blocks where needed through the theme editor
6. Test thoroughly — verify functionality works identically

If the app doesn't support app blocks, contact the developer — or consider switching to a competitor that does. Legacy code injection is a pattern that Shopify is actively moving away from, and apps that don't support blocks will become increasingly incompatible with new themes.

The Shopify experts network can help audit your theme for legacy app code and manage the migration safely.

Common Mistakes When Working With Blocks and Sections

Mistake #1: Using Sections When Blocks Would Be Cleaner

If merchants need to add, remove, and reorder individual items (FAQ questions, team members, testimonials), those should be blocks inside a section — not separate sections. Using 10 single-item sections when one section with 10 blocks would work creates editor clutter and a worse merchant experience.

Mistake #2: Not Supporting @app in Key Sections

If your product page section doesn't accept "@app" blocks, merchants can't place app widgets (reviews, size charts, trust badges) where they naturally belong. This forces apps to use less elegant injection methods.

Mistake #3: Ignoring the 50-Block Limit

Each section supports a maximum of 50 blocks. If a section might realistically contain more than 50 items (e.g., a large FAQ or gallery), consider splitting into multiple sections or paginating the content.

Mistake #4: Duplicating Block Definitions Across Sections

If three sections all need a "button" block with the same settings, create a theme block in /blocks/button.liquid and use "@theme" in each section. Don't copy-paste the block definition.

Mistake #5: Not Cleaning Up After App Uninstallation

Legacy apps leave code in your theme after uninstallation. App blocks don't — but only if the app was using the modern extension system. After uninstalling any app, check your theme code for orphaned snippets and script tags.

Quick Reference: The Decision Flowchart

When deciding between sections, theme blocks, section blocks, and app blocks:

1. Is this a standalone page module? → Section
2. Is this a repeatable item inside a section?

• Used in only one section? → Section block
• Used across multiple sections? → Theme block

1. Is this functionality from a third-party app? → App block
2. Does this need to be added/removed by merchants without code? → Block (any type)
3. Does this need its own settings panel at the page level? → Section

Understanding the distinction between Shopify app blocks vs theme sections is foundational to building themes that are clean, performant, and pleasant for merchants to customize. The architecture decisions you make now determine how maintainable your theme is for years to come.

What block architecture questions are you working through? Share them with the Talk Shop community — we debug theme architecture daily.

About Talk Shop

The Talk Shop team — insights from our community of Shopify developers, merchants, and experts.