Skip to main content
The Custom Liquid section allows you to add custom Liquid code directly to your storefront without editing theme files. Requires knowledge of Liquid (Shopify’s templating language) and is perfect for advanced customizations, dynamic content from metafields, third-party integrations, and custom product displays.

​
What this section controls

This section controls custom code integration with the following capabilities:
  • Custom Liquid templating code execution
  • HTML, CSS, and JavaScript insertion
  • Access to all Shopify Liquid objects (shop, product, collection, cart, customer)
  • Liquid filters and logic operations
  • Metafield data display
  • Third-party script integration
  • Color scheme selection for section container
  • Width and spacing controls
Requires knowledge of Liquid, Shopify’s templating language. Incorrect code can break your store’s layout or functionality. Always test in a development theme first.

​
Settings

​
Custom Liquid Code

Type: Liquid code editor
Purpose: Enter custom Liquid, HTML, CSS, or JavaScript code This multi-line code editor accepts:
  • Liquid - Shopify templating language ({{ }}, {% %} tags)
  • HTML - Structure and content markup
  • CSS - Inline styles (wrap in <style> tags)
  • JavaScript - Client-side functionality (wrap in <script> tags)
Access to Liquid objects:
  • shop - Store information
  • product - Current product (on product pages)
  • collection - Current collection (on collection pages)
  • cart - Cart data
  • customer - Logged-in customer data
  • All global Liquid objects and filters

​
Common Settings

Options: Theme color schemes (scheme-1, scheme-2, etc.)
Default: scheme-1Purpose: Apply background and text colors from theme’s color scheme to the custom liquid section container.Note: Custom CSS within your liquid code can override these colors.
Options:
  • Page - Standard page width container
  • Fluid - Full-width with padding
  • Full - 100% width, no padding
Default: PagePurpose: Control how wide your custom liquid content appears. Choose “Full” for edge-to-edge layouts.
Options: None, S, M, L, XL
Default: MVertical margin above section. See Common Settings for details.
Options: None, S, M, L, XL
Default: MVertical margin below section. See Common Settings for details.
Options: None, Top, Bottom, Both
Default: NoneAdd decorative borders above/below section. See Common Settings for details.

​
Use Cases

Custom Product Grid

Display products from specific collection with custom layout, filtering, or sorting logic using Liquid loops and conditionals.

Metafield Display

Show custom metafields (size charts, specifications, certifications) that aren’t natively supported by theme sections.

Dynamic Banners

Create conditional banners that display based on cart value, customer tags, product availability, or other dynamic data.

Third-Party Widgets

Embed widgets from external services (analytics, chat, tracking pixels) that require custom HTML/JavaScript.

Custom Calculations

Build product configurators, price calculators, or bundle pricing displays with Liquid math filters.

Advanced Filtering

Create custom collection filters beyond theme’s built-in options using Liquid conditionals and product tags.

​
Examples

​
Display Products from Collection

{% assign featured_products = collections['summer-sale'].products %}
<div class="custom-product-grid">
  {% for product in featured_products limit: 4 %}
    <div class="product-card">
      <a href="{{ product.url }}">
        <img src="{{ product.featured_image | image_url: width: 400 }}" 
             alt="{{ product.title }}">
        <h3>{{ product.title }}</h3>
        <p>{{ product.price | money }}</p>
      </a>
    </div>
  {% endfor %}
</div>

<style>
  .custom-product-grid {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: 2rem;
  }
  .product-card img {
    width: 100%;
    height: auto;
  }
</style>

​
Show Metafield Data

{% if product.metafields.custom.size_chart %}
  <div class="size-chart-section">
    <h3>Size Chart</h3>
    {{ product.metafields.custom.size_chart }}
  </div>
{% endif %}

​
Conditional Banner Based on Cart Value

{% if cart.total_price > 5000 %}
  <div class="free-shipping-banner">
    You've qualified for free shipping!
  </div>
{% else %}
  {% assign remaining = 5000 | minus: cart.total_price %}
  <div class="almost-free-shipping">
    Add {{ remaining | money }} more to qualify for free shipping
  </div>
{% endif %}

​
Custom HTML/CSS/JavaScript Widget

<div class="countdown-widget">
  <p>Sale ends in: <span id="countdown"></span></p>
</div>

<script>
  const countdownDate = new Date('2026-12-31T23:59:59').getTime();
  
  const timer = setInterval(function() {
    const now = new Date().getTime();
    const distance = countdownDate - now;
    
    const days = Math.floor(distance / (1000 * 60 * 60 * 24));
    const hours = Math.floor((distance % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
    
    document.getElementById('countdown').innerHTML = days + 'd ' + hours + 'h';
    
    if (distance < 0) {
      clearInterval(timer);
      document.getElementById('countdown').innerHTML = 'EXPIRED';
    }
  }, 1000);
</script>

<style>
  .countdown-widget {
    background: #f5f5f5;
    padding: 2rem;
    text-align: center;
    font-size: 1.5rem;
  }
</style>

​
Best practices

Test in Development Theme

Always test custom liquid code in a development/preview theme before publishing to live store. Errors can break your storefront.

Comment Your Code

Add comments explaining what code does. Makes troubleshooting easier: {% comment %}Show products from summer collection{% endcomment %}

Validate HTML/CSS

Use validators (W3C HTML Validator, CSS Validator) to check code syntax before deploying.

Optimize Images

Use Liquid image filters (image_url, image_tag) with width/height parameters to serve optimized images.

Handle Missing Data

Use conditionals to check if data exists before displaying: {% if product.metafields.custom.size_chart %}

Keep Code Maintainable

Break complex logic into smaller snippets. Reuse snippets with {% render 'snippet-name' %} for cleaner code.

Performance Considerations

Avoid heavy Liquid loops (e.g., looping through all products). Limit API calls and external scripts to maintain fast load times.

Mobile Responsiveness

Test custom layouts on mobile devices. Use CSS media queries or responsive grid layouts for mobile compatibility.

​
Liquid Resources

​
Official Documentation

​
Learning Resources

  • Shopify Liquid Cheat Sheet - Quick reference guide
  • Liquid Code Examples - Community examples on GitHub
  • Shopify Partners Blog - Tutorials and best practices

​
Troubleshooting

Common causes:
  • Syntax error in Liquid code (missing {% endif %}, unmatched tags)
  • Unclosed HTML tags (<div> without </div>)
  • JavaScript errors (check browser console)
Solution:
  • Check for syntax errors (missing closing tags, typos)
  • Use browser developer tools (F12) to check console for JavaScript errors
  • Validate HTML/CSS with online validators
  • Remove code and add back section by section to isolate error
Possible causes:
  • Object not available in current page context (e.g., product object only on product pages)
  • Incorrect object/property name
  • Object is nil/null (data doesn’t exist)
Solution:
  • Check Liquid Objects documentation for object availability
  • Use conditionals to check if object exists: {% if product %}{{ product.title }}{% endif %}
  • Verify property names match Liquid documentation
Solution:
  • Ensure CSS wrapped in <style> tags
  • Check CSS specificity (theme styles may override custom CSS)
  • Use !important sparingly to force styles (not recommended long-term)
  • Inspect element in browser to see which styles are applied/overridden
Solution:
  • Ensure JavaScript wrapped in <script> tags
  • Check browser console (F12 → Console tab) for errors
  • Verify DOM elements exist before manipulating (getElementById returns null if element doesn’t exist)
  • Use DOMContentLoaded event to ensure page loaded before running scripts
Solution:
  • Theme’s global styles may conflict with custom code
  • Check Common Settings (Color Scheme, Section Width) which affect container styles
  • Use custom CSS classes to override theme styles
  • Test with Section Width set to “Full” to remove container constraints

​
Security & Performance

Security considerations:
  • Never expose API keys or sensitive data in custom liquid code (visible in page source)
  • Validate and sanitize user input if accepting data (forms, URL parameters)
  • Be cautious with third-party scripts - only embed trusted sources
Performance tips:
  • Limit Liquid loops (e.g., limit: 10 instead of looping all products)
  • Use lazy loading for images
  • Minimize external scripts and API calls
  • Cache dynamic data when possible (use metafields for static data)

​
Key Takeaways

  • Requires Liquid knowledge - Advanced feature for developers or technical users
  • Test before deploying - Always test in development theme to avoid breaking live store
  • Access to Liquid objects - Full access to shop, product, cart, customer data
  • HTML/CSS/JavaScript supported - Build custom layouts, styles, and functionality
  • Flexible width options - Page, Fluid, or Full width for different layout needs
  • Handle missing data - Use conditionals to check data exists before displaying
Custom Liquid section provides unlimited flexibility for advanced store customization beyond standard theme sections.