RAXXO Studios

Posted on Mar 31 • Originally published at raxxo.shop

Shopify Liquid Sections: A Developer's Quick Reference

#ai #productivity #claudecode #automation

Shopify Liquid sections contain three parts in one .liquid file: HTML/Liquid template, CSS/JS, and schema JSON configuration.
Always prefix CSS class names with a unique identifier to prevent conflicts with theme styles and simplify debugging.
Use blocks in schema to let store owners add, remove, and reorder repeatable content like FAQs or testimonials.
Implement mobile-first responsive design using CSS Grid with breakpoints at 768px and 1024px for consistent layouts.
Common schema settings: text, textarea, richtext, image_picker, url, color, range, select, and checkbox for editing flexibility.

Shopify's documentation for Liquid sections is thorough but scattered across dozens of pages. After building 40+ custom sections for raxxo.shop, I compiled the patterns that come up repeatedly into one reference. Bookmark this and save yourself the documentation spelunking.

Section Anatomy

Every Liquid section has three parts: the HTML/Liquid template, the CSS/JS, and the schema JSON. They live in a single .liquid file:

<!-- Template -->
<div class="rx-my-section">
  <h2>{{ section.settings.heading }}</h2>
  <p>{{ section.settings.text }}</p>
</div>

<!-- Styles -->
<style>
  .rx-my-section { padding: 64px 0; }
</style>

<!-- Schema -->
{% schema %}
{
  "name": "My Section",
  "settings": [
    { "type": "text", "id": "heading", "label": "Heading", "default": "Hello" },
    { "type": "richtext", "id": "text", "label": "Body text" }
  ],
  "presets": [{ "name": "My Section" }]
}
{% endschema %}

CSS Isolation: Prefix Everything

This is the single most important lesson. Shopify themes have hundreds of CSS rules. If you use generic class names like .hero or .container, you will have conflicts. Guaranteed.

Pick a prefix and use it everywhere. Every RAXXO section uses rx-:

.rx-hero-wrap { ... }
.rx-hero-heading { ... }
.rx-hero-cta { ... }

This also makes debugging easier - you can instantly tell which styles are yours and which belong to the theme.

Common Schema Setting Types

The settings you'll use 90% of the time:

text - single line input
textarea - multi-line input
richtext - WYSIWYG editor (outputs HTML)
image_picker - media library image selector
url - link picker (products, collections, pages, or custom URL)
color - color picker with hex output
range - slider with min/max/step
select - dropdown with predefined options
checkbox - boolean toggle

Blocks for Repeatable Content

Blocks let store owners add, remove, and reorder items within a section. Perfect for feature lists, testimonials, team members, or FAQ items:

{% schema %}
{
  "name": "FAQ Section",
  "blocks": [
    {
      "type": "faq_item",
      "name": "FAQ Item",
      "settings": [
        { "type": "text", "id": "question", "label": "Question" },
        { "type": "richtext", "id": "answer", "label": "Answer" }
      ]
    }
  ]
}
{% endschema %}

Loop through blocks in your template:

{% for block in section.blocks %}
  <div class="rx-faq-item" {{ block.shopify_attributes }}>
    <h3>{{ block.settings.question }}</h3>
    {{ block.settings.answer }}
  </div>
{% endfor %}

Always include {{ block.shopify_attributes }} - it enables the theme editor's click-to-select behavior.

Responsive Design Patterns

Mobile-first is non-negotiable. Here's the pattern I use in every section:

.rx-section-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 24px;
  padding: 64px 20px;
  max-width: 1200px;
  margin: 0 auto;
}

@media (min-width: 768px) {
  .rx-section-grid {
    grid-template-columns: repeat(2, 1fr);
    padding: 64px 40px;
  }
}

@media (min-width: 1024px) {
  .rx-section-grid {
    grid-template-columns: repeat(3, 1fr);
  }
}

Consistent padding matters. Every section on raxxo.shop uses 64px top and bottom padding. This creates rhythm across the page without sections feeling cramped or floating.

Working with Images

Always use Shopify's image transformation URLs for performance:

{% if section.settings.image != blank %}
  <img
    src="{{ section.settings.image | image_url: width: 800 }}"
    srcset="
      {{ section.settings.image | image_url: width: 400 }} 400w,
      {{ section.settings.image | image_url: width: 800 }} 800w,
      {{ section.settings.image | image_url: width: 1200 }} 1200w"
    sizes="(max-width: 768px) 100vw, 50vw"
    alt="{{ section.settings.image.alt | escape }}"
    loading="lazy"
    width="{{ section.settings.image.width }}"
    height="{{ section.settings.image.height }}"
  >
{% endif %}

This gives you responsive images, lazy loading, proper alt text, and prevents layout shift - all the performance wins in one snippet.

Color Settings with CSS Variables

Let store owners customize colors without editing code:

<div class="rx-cta" style="
  --rx-bg: {{ section.settings.bg_color }};
  --rx-text: {{ section.settings.text_color }};
  --rx-accent: {{ section.settings.accent_color }};
">
  ...
</div>

<style>
.rx-cta {
  background: var(--rx-bg, #1f1f21);
  color: var(--rx-text, #F5F5F7);
}
.rx-cta a {
  color: var(--rx-accent, #e3fc02);
}
</style>

The fallback values in var() mean the section looks good even before the store owner customizes anything.

Icons Without a Library

You can't use React icon libraries in Liquid. Instead, inline SVG icons directly. Phosphor Icons provides clean SVGs that work well:

<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="#E0E0E0" viewBox="0 0 256 256">
  <path d="..." />
</svg>

Copy the SVG markup from phosphoricons.com, set the fill color, and paste it directly into your Liquid template. No build step, no dependencies.

Section Groups and JSON Templates

Shopify's JSON templates let you compose pages from sections in the theme editor. Create a template file like page.custom.json:

{
  "sections": {
    "hero": { "type": "rx-hero", "settings": {} },
    "features": { "type": "rx-features", "settings": {} }
  },
  "order": ["hero", "features"]
}

Then assign the template to any page in the Shopify admin. This gives maximum flexibility without code changes.

Performance Tips

Keep CSS in the section file. One less HTTP request and it only loads when the section is used.
Avoid inline JavaScript when possible. If you need JS, use defer or load it at the bottom.
Use loading="lazy" on all images below the fold.
Minimize Liquid loops. Complex nested loops slow down server-side rendering.
Test with Shopify's theme analyzer to catch performance issues before they affect your store speed score.

Debugging

When a section breaks and the error message is unhelpful (which is often), these help:

Check the schema JSON - a missing comma or bracket breaks the entire section silently
Use {{ section.settings | json }} to dump all settings and verify data is flowing
Test in preview mode before saving - the theme editor shows errors more clearly than the live site
Validate your HTML - unclosed tags in Liquid can cascade into bizarre layout issues

For reference, every custom section built for raxxo.shop is available in the RAXXO Studios repository under shop/sections/. If you want to see real-world examples of these patterns in action, that's the place to look.

DEV Community