Skip to main content

Blocks

Blocks are the modular, granular UI components that reside within Sections. They represent the third level of the Soppiya theme hierarchy (Layout > Template > Section > Block).

By breaking sections down into blocks, developers can create highly flexible layouts. Instead of hardcoding content into a section, blocks allow merchants to add, remove, and reorder specific elements—such as headings, images, or buttons—dynamically within the Soppiya Visual Editor.

Folder Location​

Unlike local section blocks, Soppiya utilizes a dedicated /blocks directory for Global Reusable Blocks. This architectural choice ensures that a single block definition can be utilized across multiple different sections, maintaining design consistency across the storefront.

└── theme
    └── blocks
        ├── title.liquid      # Reusable heading component
        ├── button.liquid     # Global call-to-action block
        └── icon-item.liquid  # Standardized icon + text unit

Key Features of Soppiya Blocks​

  • Atomic Reusability: Create a UI element once (e.g., title.liquid) and inject it into a "Hero Banner," a "Newsletter Section," or a "Product Highlight" without duplicating code.
  • Independent Settings: Each block instance carries its own unique settings. Two "Title" blocks in the same section can have different text, colors, and font sizes.
  • Visual Manipulation: Merchants can drag-and-drop blocks in the sidebar of the Visual Editor to instantly change the vertical stack of content within a section.

Technical Implementation​

Defining a Block (blocks/title.liquid)​

A block file contains the HTML/Liquid markup and a {% schema %} tag to define its administrative interface.

<!-- blocks/title.liquid -->
<div class="block-title" style="text-align: {{ block.settings.alignment }};">
  <h2 class="{{ block.settings.size }}">
    {{ block.settings.text | default: "Default Heading" }}
  </h2>
</div>

{% schema %}
{
  "name": "Heading",
  "settings": [
    {
      "type": "text",
      "id": "text",
      "label": "Heading Text"
    },
    {
      "type": "select",
      "id": "size",
      "label": "Font Size",
      "options": [
        { "value": "h1", "label": "Large" },
        { "value": "h2", "label": "Medium" },
        { "value": "h3", "label": "Small" }
      ],
      "default": "h2"
    },
    {
      "type": "text_alignment",
      "id": "alignment",
      "label": "Alignment",
      "default": "center"
    }
  ]
}
{% endschema %}

2. Rendering Blocks in a Section​

To allow a section to accept these blocks, you must define them in the section's schema and use a Liquid loop to render them in the content area.

<!-- sections/featured-banner.liquid -->
<section class="banner-wrapper">
  {% for block in section.blocks %}
    <div {{ block.shopify_attributes }}>
      {% case block.type %}
        {% when 'title' %}
          {% render 'block-title', block: block %}
        {% when 'button' %}
          {% render 'block-button', block: block %}
      {% endcase %}
    </div>
  {% endfor %}
</section>

Best Practices for Blocks​

important

Block Scoping: Use the block.settings object to access data within a block file. Do not confuse this with section.settings, which refers to the parent container's configuration.

note

Editor Compatibility: Always include {{ block.shopify_attributes }} on the wrapper element of your block inside the section's loop. This allows the Soppiya Visual Editor to highlight the block when the merchant clicks on it in the preview window.

tip

Consistency is Key: Use blocks to standardize UI patterns. If your theme requires a "Call to Action" button, creating a single button.liquid block ensures that all buttons across the site share the same hover effects and border-radius, even if their links and labels differ.

warning

Limit Block Types: While blocks offer flexibility, providing too many block types within a single section can overwhelm the merchant. Only enable block types that are relevant to the section's specific purpose.