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

> Developer section for injecting custom Liquid code, app snippets, and advanced customizations

## What It Does

The **Custom Liquid** section provides a code editor within the theme customizer, allowing developers to inject custom Liquid code, include app snippets, or create advanced customizations without editing theme files directly. This is the designated area for technical modifications and custom functionality.

## Getting Started

<Steps>
  <Step title="Add the Section">
    Add the Custom Liquid section to any template where you need custom code functionality
  </Step>

  <Step title="Write or Paste Liquid Code">
    Use the code editor to write Liquid markup, HTML, CSS, or JavaScript wrapped in appropriate tags
  </Step>

  <Step title="Test Thoroughly">
    Preview your changes carefully before publishing. Invalid Liquid can cause rendering issues
  </Step>

  <Step title="Adjust Spacing">
    Set top and bottom padding to control vertical spacing around your custom content
  </Step>
</Steps>

## Settings

<AccordionGroup>
  <Accordion title="Custom Liquid" icon="code">
    **Type:** Liquid code editor\
    **Default:** Empty

    A code editor field where you can write or paste custom Liquid code, HTML, CSS, or JavaScript. This field has full access to Liquid objects, filters, and tags available in Shopify themes.

    ### What You Can Add

    **App Snippets:**

    ```liquid theme={null}
    {% render 'app-reviews' %}
    {% render 'size-chart' %}
    ```

    Integrate third-party apps by rendering their snippets. Most Shopify apps provide snippet code for integration.

    **Custom Product Grids:**

    ```liquid theme={null}
    {% assign featured = collections.featured.products %}
    {% for product in featured limit: 4 %}
      <!-- Custom product card HTML -->
    {% endfor %}
    ```

    Create customized product displays beyond standard section capabilities.

    **Dynamic Content:**

    ```liquid theme={null}
    {% if customer %}
      <p>Welcome back, {{ customer.first_name }}!</p>
    {% else %}
      <p>Sign in to see personalized content</p>
    {% endif %}
    ```

    Show different content based on customer login status, cart contents, or other conditions.

    **Custom Forms:**

    ```liquid theme={null}
    <form action="/cart/add" method="post">
      <!-- Custom form fields -->
      <button type="submit">Add to Cart</button>
    </form>
    ```

    Build custom forms for contact, newsletter, or product customization.

    **Embedded Content:**

    ```liquid theme={null}
    <iframe src="https://example.com/widget" width="100%" height="400"></iframe>
    ```

    Embed external widgets, calendars, booking systems, or third-party content.

    **Custom CSS/JavaScript:**

    ```liquid theme={null}
    <style>
      .custom-element { color: red; }
    </style>
    <script>
      console.log('Custom functionality');
    </script>
    ```

    Add page-specific styling or functionality (wrap in appropriate tags).

    ### Code Editor Features

    * **Syntax highlighting:** Liquid, HTML, CSS, and JavaScript syntax coloring
    * **Line numbers:** Easy reference for debugging
    * **Indentation support:** Tab key for proper code formatting
    * **Error highlighting:** Basic syntax error detection (not foolproof)

    ### Important Guidelines

    **Do:**

    * Test code in a duplicate/staging theme first
    * Use comments to document what custom code does
    * Follow Liquid best practices and syntax
    * Validate HTML to ensure proper structure
    * Keep code organized and readable

    **Don't:**

    * Copy-paste code you don't understand
    * Include unescaped customer input (security risk)
    * Create very long code blocks (use snippets instead)
    * Forget to test on mobile devices
    * Override critical theme functionality without backup

    ### Security Considerations

    The Custom Liquid section has **full theme access**, meaning:

    * Code executes server-side during page render
    * Has access to all Liquid objects (customer data, products, orders)
    * Can modify page structure and functionality
    * Can include external resources

    **Never include:**

    * API keys or passwords in plain text
    * Unvalidated customer input that could execute malicious code
    * Resource-intensive operations that slow page rendering
    * Code from untrusted sources

    ### Performance Tips

    * **Limit API calls:** Liquid executes server-side; excessive API calls slow page rendering
    * **Cache when possible:** Use Liquid variables to avoid repeated calculations
    * **Minimize external resources:** Each external script/style adds load time
    * **Test load time:** Use browser dev tools to ensure custom code doesn't create bottlenecks
  </Accordion>

  <Accordion title="Padding Top" icon="arrow-up">
    **Type:** Range slider\
    **Range:** 0-100px (increments of 4px)\
    **Default:** 40px

    Vertical spacing (padding) above the custom liquid content. Controls distance from the previous section or page element.

    ### When to Adjust

    **Increase (60-100px):**

    * Custom content is visually prominent (needs breathing room)
    * Creating hero-like custom sections
    * Content needs clear separation from above section

    **Decrease (20-36px):**

    * Custom content is supplementary (subtle addition)
    * Multiple custom liquid sections stacked closely
    * Tighter, content-dense layouts

    **Remove (0px):**

    * Custom content is continuous with previous section
    * Building integrated custom layouts
    * Advanced design scenarios with custom spacing

    **Default (40px):** Appropriate for most use cases, providing standard section spacing.
  </Accordion>

  <Accordion title="Padding Bottom" icon="arrow-down">
    **Type:** Range slider\
    **Range:** 0-100px (increments of 4px)\
    **Default:** 52px

    Vertical spacing (padding) below the custom liquid content. Controls distance to the next section or page element.

    ### When to Adjust

    **Increase (60-100px):**

    * Custom content concludes a major page section
    * Creating visual breaks between distinct page areas
    * Custom content needs clear ending

    **Decrease (20-36px):**

    * Next section is closely related
    * Reducing cumulative whitespace on long pages
    * Tighter layouts

    **Remove (0px):**

    * Next section is continuous part of custom layout
    * Building integrated custom designs
    * Advanced spacing control

    **Default (52px):** Slightly more than padding top, providing balanced section conclusion spacing.

    ### Padding Coordination

    The default values (40px top, 52px bottom) create **92px total vertical spacing** around custom content. Adjust both values proportionally to maintain visual balance unless you specifically need asymmetric spacing.
  </Accordion>
</AccordionGroup>

## Best practices

<CardGroup cols={2}>
  <Card title="Test in Duplicate Theme First" icon="vial">
    Always test custom Liquid in a duplicate/staging theme before implementing in your live theme. Invalid code can break page rendering.
  </Card>

  <Card title="Document Your Code" icon="comment">
    Add comments explaining what custom code does and why it's there. Future you (or other developers) will appreciate the context.
  </Card>

  <Card title="Keep Code Organized" icon="list-check">
    For complex customizations, create a snippet file and render it from Custom Liquid section rather than writing 100+ lines inline.
  </Card>

  <Card title="Validate Before Publishing" icon="check">
    Use HTML validators and Liquid syntax checkers to catch errors before they reach customers. Preview extensively on desktop and mobile.
  </Card>

  <Card title="Avoid Hardcoded Values" icon="link-slash">
    Use Liquid variables and settings rather than hardcoding product IDs, URLs, or text. Makes maintenance easier when things change.
  </Card>

  <Card title="Consider Performance Impact" icon="gauge">
    Monitor page load time after adding custom Liquid. Heavy operations, many API calls, or large external scripts can slow rendering significantly.
  </Card>

  <Card title="Never Expose Sensitive Data" icon="lock">
    Don't include API keys, passwords, or sensitive credentials in Custom Liquid. Use secure app integrations or backend logic instead.
  </Card>

  <Card title="Mobile-First Approach" icon="mobile">
    Always test custom code on mobile devices. What works on desktop may have layout or performance issues on mobile connections.
  </Card>
</CardGroup>

## Common Use Cases

### App Snippet Integration

**Use case:** Integrating third-party Shopify apps that provide snippet code

```liquid theme={null}
{% comment %}
  Render app snippet for product reviews
  App: Judge.me Product Reviews
{% endcomment %}
{% render 'judgeme_widgets' %}
```

**When to use:** Apps requiring snippet placement in specific templates (homepage, product page, cart)

### Custom Product Showcase

**Use case:** Featured products with custom layout beyond standard sections

```liquid theme={null}
{% assign featured = collections.featured.products %}
<div class="custom-product-grid">
  {% for product in featured limit: 4 %}
    <div class="product-card">
      <a href="{{ product.url }}">
        <img src="{{ product.featured_image | img_url: 'medium' }}" 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(auto-fit, minmax(250px, 1fr));
    gap: 20px;
  }
</style>
```

**When to use:** Unique homepage product displays, curated collections, custom styling

### Personalized Welcome Message

**Use case:** Show different content to logged-in vs guest customers

```liquid theme={null}
{% if customer %}
  <div class="welcome-message">
    <h2>Welcome back, {{ customer.first_name }}!</h2>
    <p>You have {{ customer.orders_count }} orders with us.</p>
    <a href="/account">View Your Account</a>
  </div>
{% else %}
  <div class="welcome-message">
    <h2>New Here?</h2>
    <p>Create an account to track orders and save favorites.</p>
    <a href="/account/register">Sign Up</a>
  </div>
{% endif %}
```

**When to use:** Personalized homepage content, account pages, post-purchase experiences

### Conditional Announcement Banners

**Use case:** Show banners only to specific customer segments or during specific times

```liquid theme={null}
{% comment %} Show holiday banner only in December {% endcomment %}
{% assign current_month = 'now' | date: '%m' %}
{% if current_month == '12' %}
  <div class="holiday-banner" style="background: #c41e3a; color: white; padding: 20px; text-align: center;">
    <h2>Holiday Sale: 25% Off Storewide Until Dec 25!</h2>
    <a href="/collections/all" style="color: white; text-decoration: underline;">Shop Now</a>
  </div>
{% endif %}
```

**When to use:** Seasonal promotions, customer segment targeting, A/B testing custom banners

### External Widget Embedding

**Use case:** Integrate booking system, event calendar, or external tool

```liquid theme={null}
{% comment %} Embed appointment booking widget {% endcomment %}
<div class="booking-widget">
  <h2>Book a Consultation</h2>
  <iframe 
    src="https://calendly.com/your-store/consultation" 
    width="100%" 
    height="600" 
    frameborder="0">
  </iframe>
</div>

<style>
  .booking-widget {
    max-width: 800px;
    margin: 0 auto;
  }
</style>
```

**When to use:** Service-based businesses, appointment booking, event registration, external integrations

### Cart-Based Conditional Content

**Use case:** Show different messages based on cart contents or value

```liquid theme={null}
{% if cart.item_count > 0 %}
  {% assign cart_total = cart.total_price | money_without_currency | plus: 0 %}
  {% if cart_total < 50 %}
    <div class="free-shipping-notice" style="background: #fef3c7; padding: 15px; text-align: center; border-radius: 8px;">
      <p>Add ${{ 50 | minus: cart_total }} more for FREE SHIPPING!</p>
    </div>
  {% else %}
    <div class="free-shipping-notice" style="background: #d1fae5; padding: 15px; text-align: center; border-radius: 8px;">
      <p>You've qualified for FREE SHIPPING!</p>
    </div>
  {% endif %}
{% endif %}
```

**When to use:** Cart page upsells, shipping threshold notices, volume discount triggers

## Technical Notes

### Liquid Object Access

The Custom Liquid section has full access to Shopify's Liquid objects based on template context:

**Available Everywhere:**

* `shop` - Store information
* `cart` - Current cart contents
* `request` - Page request information
* `settings` - Theme settings
* `template` - Current template name

**Template-Specific:**

* `product` - Product template only
* `collection` - Collection template only
* `article` - Article/blog template only
* `page` - Page template only
* `customer` - All templates (null if not logged in)

**Not Available:**

* Section-specific settings from other sections (isolated scope)
* Data from apps unless they provide Liquid objects

### Server-Side vs Client-Side Execution

**Server-Side (Liquid):**

* Executes during page render on Shopify servers
* Has access to all Shopify data (products, customers, orders)
* Output is HTML sent to browser
* Cannot respond to user interactions after page load

**Client-Side (JavaScript):**

* Executes in customer's browser after page loads
* Can respond to clicks, scrolls, form submissions
* Must use Ajax/fetch to access Shopify data
* Use `<script>` tags within Custom Liquid for client-side code

### Code Limitations

* **No file system access:** Cannot create/read files outside Liquid scope
* **No database queries:** Can only access data through Liquid objects
* **No external API calls:** Liquid doesn't support HTTP requests to external services
* **Output buffering:** Very large output (thousands of lines) may be truncated

### Snippet Alternative

For complex or reusable custom code, consider creating a **snippet file** instead:

1. Create `snippets/custom-homepage-hero.liquid` in theme code editor
2. Write full code in snippet file (easier editing, version control)
3. Use Custom Liquid section to render snippet:

```liquid theme={null}
{% render 'custom-homepage-hero' %}
```

**Benefits:**

* Easier code editing (full code editor vs. small inline field)
* Reusable across multiple pages
* Better organization
* Easier version control/backup

### Debugging Custom Liquid

**Common Issues:**

**Nothing displays:**

* Check for Liquid syntax errors (missing `%}`, unclosed tags)
* Verify objects exist (e.g., `product` only exists on product pages)
* Check padding isn't set too low (content might be hidden)

**Page renders incorrectly:**

* Validate HTML structure (unclosed tags break layout)
* Check for CSS specificity conflicts with theme styles
* Verify JavaScript isn't conflicting with theme scripts

**Performance problems:**

* Remove expensive operations (nested loops, large arrays)
* Limit external script/style includes
* Cache repeated calculations in variables

**Use Liquid's debug filter:**

```liquid theme={null}
{{ product | json }}
```

Outputs object structure to inspect available data.

### Security Best Practices

* **Sanitize user input:** Never directly output customer-submitted data without escaping
* **Use `escape` filter:** `{{ user_input | escape }}` prevents XSS attacks
* **Validate external resources:** Only include scripts/styles from trusted sources
* **Avoid inline credentials:** Never hardcode API keys or passwords
* **Test for injection attacks:** Ensure form inputs can't execute code

### Performance Monitoring

After adding custom Liquid:

1. Use browser DevTools Network tab to check page load time
2. Monitor server response time in Shopify admin (Online Store > Themes > Actions > Preview)
3. Test on slow connections (DevTools network throttling)
4. Check mobile performance (often slower than desktop)

**Target:** Custom Liquid should add less than 100ms to page load time.

## Troubleshooting

**Custom Liquid section is empty/not displaying:**

* Verify code is saved (click Save after editing)
* Check Liquid syntax for errors (unclosed tags, typos in object names)
* Ensure template context matches code (e.g., `product` object only exists on product pages)
* Check padding settings aren't set to 0 with no content height

**Layout breaks after adding custom code:**

* Validate HTML structure (use W3C validator)
* Check for unclosed `<div>`, `<style>`, or `<script>` tags
* Verify custom CSS isn't overriding critical theme styles
* Inspect with browser DevTools to identify conflicting styles

**Code works on desktop but not mobile:**

* Test responsive behavior (fixed widths may overflow)
* Check external resources load on mobile connections
* Verify JavaScript doesn't rely on desktop-specific events
* Test iframe embeds (some services don't work well on mobile)

**Performance degradation after adding custom Liquid:**

* Remove or optimize nested Liquid loops
* Limit external script/style includes (each adds HTTP request)
* Cache repeated operations in variables rather than recalculating
* Consider moving heavy logic to snippet file with error handling

**App snippet not rendering:**

* Verify app is installed and enabled
* Check snippet name matches exactly (case-sensitive)
* Ensure app hasn't been updated with new snippet name
* Review app's integration instructions for template compatibility

**JavaScript errors in console:**

* Check for syntax errors in `<script>` tags
* Verify jQuery/libraries are loaded if code depends on them
* Ensure code doesn't conflict with theme's existing JavaScript
* Wrap code in `DOMContentLoaded` to ensure DOM is ready