> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digifist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Liquid

> Add custom Liquid code to your storefront for advanced customization

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

<Warning>
  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.
</Warning>

## 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

<Accordion title="Color Scheme">
  **Options:** Theme color schemes (scheme-1, scheme-2, etc.)\
  **Default:** scheme-1

  **Purpose:** 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.
</Accordion>

<Accordion title="Section Width">
  **Options:**

  * **Page** - Standard page width container
  * **Fluid** - Full-width with padding
  * **Full** - 100% width, no padding

  **Default:** Page

  **Purpose:** Control how wide your custom liquid content appears. Choose "Full" for edge-to-edge layouts.
</Accordion>

<Accordion title="Spacing Top">
  **Options:** None, S, M, L, XL\
  **Default:** M

  Vertical margin above section. See [Common Settings](/themes/sahara/common-settings) for details.
</Accordion>

<Accordion title="Spacing Bottom">
  **Options:** None, S, M, L, XL\
  **Default:** M

  Vertical margin below section. See [Common Settings](/themes/sahara/common-settings) for details.
</Accordion>

<Accordion title="Section Border">
  **Options:** None, Top, Bottom, Both\
  **Default:** None

  Add decorative borders above/below section. See [Common Settings](/themes/sahara/common-settings) for details.
</Accordion>

## Use Cases

<CardGroup cols={2}>
  <Card title="Custom Product Grid" icon="grid">
    Display products from specific collection with custom layout, filtering, or sorting logic using Liquid loops and conditionals.
  </Card>

  <Card title="Metafield Display" icon="database">
    Show custom metafields (size charts, specifications, certifications) that aren't natively supported by theme sections.
  </Card>

  <Card title="Dynamic Banners" icon="rectangle-ad">
    Create conditional banners that display based on cart value, customer tags, product availability, or other dynamic data.
  </Card>

  <Card title="Third-Party Widgets" icon="puzzle-piece">
    Embed widgets from external services (analytics, chat, tracking pixels) that require custom HTML/JavaScript.
  </Card>

  <Card title="Custom Calculations" icon="calculator">
    Build product configurators, price calculators, or bundle pricing displays with Liquid math filters.
  </Card>

  <Card title="Advanced Filtering" icon="filter">
    Create custom collection filters beyond theme's built-in options using Liquid conditionals and product tags.
  </Card>
</CardGroup>

## Examples

### Display Products from Collection

```liquid theme={null}
{% 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

```liquid theme={null}
{% 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

```liquid theme={null}
{% 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

```liquid theme={null}
<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

<CardGroup cols={2}>
  <Card title="Test in Development Theme" icon="flask">
    Always test custom liquid code in a development/preview theme before publishing to live store. Errors can break your storefront.
  </Card>

  <Card title="Comment Your Code" icon="comment">
    Add comments explaining what code does. Makes troubleshooting easier: `{% comment %}Show products from summer collection{% endcomment %}`
  </Card>

  <Card title="Validate HTML/CSS" icon="circle-check">
    Use validators (W3C HTML Validator, CSS Validator) to check code syntax before deploying.
  </Card>

  <Card title="Optimize Images" icon="images">
    Use Liquid image filters (`image_url`, `image_tag`) with width/height parameters to serve optimized images.
  </Card>

  <Card title="Handle Missing Data" icon="shield-exclamation">
    Use conditionals to check if data exists before displaying: `{% if product.metafields.custom.size_chart %}`
  </Card>

  <Card title="Keep Code Maintainable" icon="code">
    Break complex logic into smaller snippets. Reuse snippets with `{% render 'snippet-name' %}` for cleaner code.
  </Card>

  <Card title="Performance Considerations" icon="gauge-high">
    Avoid heavy Liquid loops (e.g., looping through all products). Limit API calls and external scripts to maintain fast load times.
  </Card>

  <Card title="Mobile Responsiveness" icon="mobile">
    Test custom layouts on mobile devices. Use CSS media queries or responsive grid layouts for mobile compatibility.
  </Card>
</CardGroup>

## Liquid Resources

### Official Documentation

* **[Shopify Liquid Documentation](https://shopify.dev/docs/api/liquid)** - Complete Liquid reference
* **[Liquid Objects](https://shopify.dev/docs/api/liquid/objects)** - Available objects (product, shop, cart, etc.)
* **[Liquid Filters](https://shopify.dev/docs/api/liquid/filters)** - Data manipulation filters
* **[Liquid Tags](https://shopify.dev/docs/api/liquid/tags)** - Control flow and logic

### Learning Resources

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="Code doesn't display or breaks layout">
    **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
  </Accordion>

  <Accordion title="Liquid objects don't work (e.g., {{ product.title }} is blank)">
    **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](https://shopify.dev/docs/api/liquid/objects) for object availability
    * Use conditionals to check if object exists: `{% if product %}{{ product.title }}{% endif %}`
    * Verify property names match Liquid documentation
  </Accordion>

  <Accordion title="Custom CSS not applying">
    **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
  </Accordion>

  <Accordion title="JavaScript not executing">
    **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
  </Accordion>

  <Accordion title="Section looks different than expected">
    **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
  </Accordion>
</AccordionGroup>

## Security & Performance

<Warning>
  **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
</Warning>

**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)

## Related Sections

* [Custom Liquid (Shopify Docs)](https://shopify.dev/docs/api/liquid) - Official Liquid documentation
* [Common Settings](/themes/sahara/common-settings) - Section-level styling options

## 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.