Custom sections

A new section is a new file in sections/. Shopify picks it up automatically — there is no registration step.

A minimal section

{%- comment -%} My Section {%- endcomment -%}

<section class="my-section" {{ section.shopify_attributes }}>
  <div class="container">
    {%- if section.settings.heading != blank -%}
      <h2 class="my-section__heading">{{ section.settings.heading }}</h2>
    {%- endif -%}

    {%- for block in section.blocks -%}
      <div class="my-section__item" {{ block.shopify_attributes }}>
        {{ block.settings.title }}
      </div>
    {%- endfor -%}
  </div>
</section>

{% schema %}
{
  "name": "My Section",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "My heading" }
  ],
  "blocks": [
    {
      "type": "item",
      "name": "Item",
      "settings": [
        { "type": "text", "id": "title", "label": "Title", "default": "Item" }
      ]
    }
  ],
  "presets": [
    { "name": "My Section", "blocks": [{ "type": "item" }] }
  ]
}
{% endschema %}

Rules

Use the design tokens

.my-section {
  padding: var(--space-section-padding) 0;
  background: var(--color-surface-container-low);
  color: var(--color-on-surface);
  border-radius: var(--radius-lg);
  border: 1px solid var(--glass-border);
}

Never hard-code a colour. background: #0b1119 will not follow the merchant’s brand; var(--color-surface-container-low) will.

Use the container class

The theme has a .container class that handles the max width and the responsive gutters. Use it rather than rolling your own.

Use `section.shopify_attributes`

On the section root element. It is what lets the theme editor and app extensions target your section.

Use `block.shopify_attributes`

On every block wrapper. Same reason.

Scope your styles

.my-section { — }
.my-section__heading { — }
.my-section__item { — }

Do not write bare element selectors like .container or h2 in a section’s style block. Section styles are global once rendered — they will leak into every other section on the page. Always scope to your section’s class.

Put the styles in a `<style>` block

{% style %}
  .my-section { — }
{% endstyle %}

The {% style %} tag is Shopify’s way of letting the theme editor move section CSS into a global stylesheet. It is the correct choice for a section.

Adding it to a template

Open the template in the theme editor and click Add section. Your new section appears in the list automatically. You do not need to edit any JSON.

If you want the section available in a template by default, you can add it to templates/*.json. But be aware that rebuilding a template from JSON can drop blocks the merchant has configured. Prefer adding sections through the editor.

Making it upgrade-safe

Do	Don’t
Add new files	Edit existing section files
Scope every selector	Use bare element selectors
Use design tokens	Hard-code colours and sizes
Put CSS in `{% style %}`	Put CSS in `assets/` for a section
Name classes `sectionname__element`	Reuse another section’s class names

VARAHI’s own section files use the same conventions. If you follow them, a future theme update will not conflict with your code.

A worked example

A “Press & awards” section with a logo row.

{%- comment -%} Press Logos {%- endcomment -%}

<section class="press" {{ section.shopify_attributes }}>
  <div class="container press__inner">
    {%- if section.settings.heading != blank -%}
      <p class="press__heading">{{ section.settings.heading }}</p>
    {%- endif -%}

    <ul class="press__list" role="list">
      {%- for block in section.blocks -%}
        <li class="press__item" {{ block.shopify_attributes }}>
          {%- if block.settings.logo != blank -%}
            <img
              src="{{ block.settings.logo | image_url: width: 200 }}"
              alt="{{ block.settings.alt | escape }}"
              width="120"
              height="40"
              loading="lazy"
            >
          {%- else -%}
            <span class="press__name">{{ block.settings.name }}</span>
          {%- endif -%}
        </li>
      {%- endfor -%}
    </ul>
  </div>
</section>

{% style %}
  .press { padding: var(--space-section-padding) 0; }
  .press__inner { text-align: center; }
  .press__heading {
    font-family: var(--font-label);
    font-size: var(--text-technical-sm);
    letter-spacing: var(--tracking-label);
    text-transform: uppercase;
    color: var(--color-on-surface-variant);
    margin-bottom: var(--space-base);
  }
  .press__list {
    display: flex; flex-wrap: wrap; gap: var(--space-grid-gutter);
    justify-content: center; list-style: none; padding: 0; margin: 0;
  }
  .press__item img { max-width: 120px; opacity: .55; transition: opacity var(--transition-fast); }
  .press__item:hover img { opacity: 1; }
{% endstyle %}

{% schema %}
{
  "name": "Press logos",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "As featured in" }
  ],
  "blocks": [
    {
      "type": "logo",
      "name": "Logo",
      "settings": [
        { "type": "image_picker", "id": "logo", "label": "Image" },
        { "type": "text", "id": "name", "label": "Name", "default": "Publication" },
        { "type": "text", "id": "alt", "label": "Alt text" }
      ]
    }
  ],
  "presets": [{ "name": "Press logos" }]
}
{% endschema %}

Code reference

The token system and the file map.

Performance

The budgets your section has to fit inside.

Getting Started

Theme Configuration

Sections & Blocks

Features

Going Further

Resources

Custom sections

Custom sections

A minimal section

Rules

Use the design tokens

Use the container class

Use `section.shopify_attributes`

Use `block.shopify_attributes`

Scope your styles

Put the styles in a `<style>` block

Adding it to a template

Making it upgrade-safe

A worked example

Code reference

Performance

​Custom sections

​A minimal section

​Rules

​Use the design tokens

​Use the container class

​Use section.shopify_attributes

​Use block.shopify_attributes

​Scope your styles

​Put the styles in a <style> block

​Adding it to a template

​Making it upgrade-safe

​A worked example

Code reference

Performance

Custom sections

A minimal section

Rules

Use the design tokens

Use the container class

Use `section.shopify_attributes`

Use `block.shopify_attributes`

Scope your styles

Put the styles in a `<style>` block

Adding it to a template

Making it upgrade-safe

A worked example