Custom Liquid - DigiFist Documentation

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

Add the Section

Add the Custom Liquid section to any template where you need custom code functionality

Write or Paste Liquid Code

Use the code editor to write Liquid markup, HTML, CSS, or JavaScript wrapped in appropriate tags

Test Thoroughly

Preview your changes carefully before publishing. Invalid Liquid can cause rendering issues

Adjust Spacing

Set top and bottom padding to control vertical spacing around your custom content

Settings

Custom Liquid

Type: Liquid code editor
Default: EmptyA 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:

{% 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:

{% 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:

{% 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:

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

<iframe src="https://example.com/widget" width="100%" height="400"></iframe>

Embed external widgets, calendars, booking systems, or third-party content.Custom CSS/JavaScript:

<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

Padding Top

Type: Range slider
Range: 0-100px (increments of 4px)
Default: 40pxVertical 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.

Padding Bottom

Type: Range slider
Range: 0-100px (increments of 4px)
Default: 52pxVertical 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.

Best practices

Test in Duplicate Theme First

Always test custom Liquid in a duplicate/staging theme before implementing in your live theme. Invalid code can break page rendering.

Document Your Code

Add comments explaining what custom code does and why it’s there. Future you (or other developers) will appreciate the context.

Keep Code Organized

For complex customizations, create a snippet file and render it from Custom Liquid section rather than writing 100+ lines inline.

Validate Before Publishing

Use HTML validators and Liquid syntax checkers to catch errors before they reach customers. Preview extensively on desktop and mobile.

Avoid Hardcoded Values

Use Liquid variables and settings rather than hardcoding product IDs, URLs, or text. Makes maintenance easier when things change.

Consider Performance Impact

Monitor page load time after adding custom Liquid. Heavy operations, many API calls, or large external scripts can slow rendering significantly.

Never Expose Sensitive Data

Don’t include API keys, passwords, or sensitive credentials in Custom Liquid. Use secure app integrations or backend logic instead.

Mobile-First Approach

Always test custom code on mobile devices. What works on desktop may have layout or performance issues on mobile connections.

Common Use Cases

App Snippet Integration

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

{% 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

{% 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

{% 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

{% 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 Use case: Integrate booking system, event calendar, or external tool

{% 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

{% 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:

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

{% 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:

{{ 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:

Use browser DevTools Network tab to check page load time
Monitor server response time in Shopify admin (Online Store > Themes > Actions > Preview)
Test on slow connections (DevTools network throttling)
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

Overview

Header

Footer

Products

Collections

Pages & Templates

Sections

​What It Does

​Getting Started

​Settings

​What You Can Add

​Code Editor Features

​Important Guidelines

​Security Considerations

​Performance Tips

​When to Adjust

​When to Adjust

​Padding Coordination

​Best practices

Test in Duplicate Theme First

Document Your Code

Keep Code Organized

Validate Before Publishing

Avoid Hardcoded Values

Consider Performance Impact

Never Expose Sensitive Data

Mobile-First Approach

​Common Use Cases

​App Snippet Integration

​Custom Product Showcase

​Personalized Welcome Message

​Conditional Announcement Banners

​External Widget Embedding

​Cart-Based Conditional Content

​Technical Notes

​Liquid Object Access

​Server-Side vs Client-Side Execution

​Code Limitations

​Snippet Alternative

​Debugging Custom Liquid

​Security Best Practices

​Performance Monitoring

​Troubleshooting

What It Does

Getting Started

Settings

What You Can Add

Code Editor Features

Important Guidelines

Security Considerations

Performance Tips

When to Adjust

When to Adjust

Padding Coordination

Best practices

Common Use Cases

App Snippet Integration

Custom Product Showcase

Personalized Welcome Message

Conditional Announcement Banners

External Widget Embedding

Cart-Based Conditional Content

Technical Notes

Liquid Object Access

Server-Side vs Client-Side Execution

Code Limitations

Snippet Alternative

Debugging Custom Liquid

Security Best Practices

Performance Monitoring

Troubleshooting