blocks + presets

Use blocks to create repeating sub-elements inside a widget (e.g., feature cards, FAQs, slides). Add presets to offer ready-made examples for the editor.

How blocks work

Each block type defines its own settings schema. The merchant can add, remove, and reorder blocks in the builder. Your template loops through widget.blocks to render them.

Schema Structure

{
  "name": "Widget Name",
  "description": "Widget description",
  "blocks": {
    "blockTypeName": {
      "name": "Block Display Name",
      "settings": {
        "keyname": { "type": "string", "label": "Label", "default": "" }
      }
    }
  },
  "presets": [
    {
      "category": "homepage",
      "name": "Preset Name",
      "blocks": [
        {
          "block": "blockTypeName",
          "name": "Item 1",
          "settings": { "keyname": "value" }
        }
      ]
    }
  ]
}

Usage

Full Example

{
  "name": "Features",
  "description": "Feature cards section",
  "blocks": {
    "feature": {
      "name": "Feature Card",
      "settings": {
        "title": { "type": "string", "label": "Title", "default": "" },
        "description": { "type": "string", "label": "Description", "default": "" },
        "icon": { "type": "media", "label": "Icon", "default": "" }
      }
    }
  },
  "presets": [
    {
      "category": "homepage",
      "name": "Features Section",
      "blocks": [
        { "block": "feature", "name": "Fast Shipping", "settings": { "title": "Fast", "description": "Quick shipping", "icon": "" } },
        { "block": "feature", "name": "Support", "settings": { "title": "Support", "description": "We are here", "icon": "" } },
        { "block": "feature", "name": "Quality", "settings": { "title": "Quality", "description": "Top rated", "icon": "" } }
      ]
    }
  ]
}

Template

<section>
  <div class="grid">
    {% for block in widget.blocks %}
      <article>
        {% if block.settings.icon %}
          <img src="{{ block.settings.icon | assets }}" alt="">
        {% endif %}
        <h3>{{ block.settings.title }}</h3>
        <p>{{ block.settings.description }}</p>
      </article>
    {% endfor %}
  </div>
</section>

Output

{
  "blocks": [
    {
      "type": "feature",
      "settings": {
        "title": "Fast",
        "description": "Quick shipping",
        "icon": ""
      }
    },
    {
      "type": "feature",
      "settings": {
        "title": "Support",
        "description": "We are here",
        "icon": ""
      }
    },
    {
      "type": "feature",
      "settings": {
        "title": "Quality",
        "description": "Top rated",
        "icon": ""
      }
    }
  ]
}

Presets

Setting "category": "homepage" inside a preset makes the widget appear by default in the homepage group in the builder.

Interactive Preview

Interactive Preview

Feature Blocks

Fast Shipping

Quick delivery

24/7 Support

Always here

Top Quality

Best products

Live Output

{
  "blocks": [
    {
      "type": "feature",
      "settings": {
        "title": "Fast Shipping",
        "description": "Quick delivery"
      }
    },
    {
      "type": "feature",
      "settings": {
        "title": "24/7 Support",
        "description": "Always here"
      }
    },
    {
      "type": "feature",
      "settings": {
        "title": "Top Quality",
        "description": "Best products"
      }
    }
  ]
}