Custom Code Section

The custom code section lets you add your own HTML, Liquid, CSS, and JavaScript code to create completely custom content and functionality. This is an advanced feature for users familiar with web development.

Overview

This section provides maximum flexibility by allowing you to write custom code. You can add HTML markup, Liquid template code, CSS styles, and JavaScript to create unique features that aren't available in standard sections.

⚠️ Important Warnings

Security Considerations

  • Only use code you trust: Never paste code from untrusted sources
  • Test thoroughly: Custom code can break your site if incorrect
  • Backup first: Always backup your theme before adding custom code
  • Validate code: Ensure code is valid and secure

Performance Considerations

  • Optimize code: Poorly written code can slow down your site
  • Test on mobile: Ensure custom code works on all devices
  • Monitor impact: Check page speed after adding custom code

Where to Use

  • Homepage: Custom widgets, integrations
  • Product pages: Custom product features
  • Any page: When you need functionality not available in standard sections

Note: This section requires technical knowledge. If you're not comfortable with code, consider using standard sections instead.

Settings

Content

Heading

  • Optional heading for the section
  • Tip: Helps identify the section in the editor

Description

  • Optional description text
  • Supports rich text formatting
  • Tip: Use to explain what the custom code does

HTML

HTML Code

  • Add custom HTML markup
  • Code is rendered directly in the page
  • Use for: Custom HTML elements, embedded content, third-party widgets

Example:

<div class="custom-widget">
  <h3>Custom Content</h3>
  <p>This is custom HTML content.</p>
</div>

Liquid

Liquid Code

  • Add custom Liquid template code
  • Code is processed by Shopify's Liquid engine
  • Use for: Dynamic content, Shopify data access, conditional logic

Example:

{% if customer %}
  <p>Welcome back, {{ customer.first_name }}!</p>
{% endif %}

Available Objects:

  • shop - Store information
  • customer - Customer data (if logged in)
  • product - Product data (on product pages)
  • collection - Collection data (on collection pages)
  • And more Shopify objects

CSS

CSS Styles

  • Add custom CSS styles
  • Styles are applied globally to your theme
  • Use for: Custom styling, theme customization, design tweaks

Example:

.custom-widget {
  background-color: #f5f5f5;
  padding: 20px;
  border-radius: 8px;
}

Important: CSS added here applies to your entire theme, not just this section. Use specific class names to avoid conflicts.

JavaScript

JavaScript Code

  • Add custom JavaScript code
  • Code executes when the page loads
  • Use for: Interactive features, third-party integrations, custom functionality

Example:

document.addEventListener('DOMContentLoaded', function() {
  console.log('Custom code loaded');
  // Your JavaScript code here
});

Important: JavaScript runs on every page load. Ensure code is efficient and doesn't conflict with theme scripts.

Section Settings

Custom Section ID

  • Optional custom ID for the section
  • Useful for JavaScript targeting or CSS styling
  • Default: Uses section ID automatically
  • Tip: Use descriptive IDs (e.g., "custom-widget-1")

Top Padding

  • Space above the section
  • Range: 0-100px
  • Default: 40px
  • Tip: Creates breathing room from previous section

Bottom Padding

  • Space below the section
  • Range: 0-100px
  • Default: 40px
  • Tip: Creates breathing room before next section

Common Use Cases

Third-Party Widgets

  • HTML: Embed third-party widgets (chat, reviews, etc.)
  • JavaScript: Initialize widget functionality
  • Example: Live chat widgets, review systems

Custom Forms

  • HTML: Custom form markup
  • JavaScript: Form handling and validation
  • CSS: Form styling
  • Example: Contact forms, newsletter signups

Analytics & Tracking

  • JavaScript: Custom tracking code
  • Example: Google Analytics events, conversion tracking

Custom Integrations

  • HTML + JavaScript: Integrate external services
  • Example: Booking systems, calculators, maps

Dynamic Content

  • Liquid: Display Shopify data dynamically
  • Example: Customer-specific content, product recommendations

Code Best Practices

HTML Best Practices

✅ Do:

  • Use semantic HTML elements
  • Include proper attributes (alt, aria-labels)
  • Keep markup clean and organized
  • Test in different browsers

❌ Don't:

  • Don't use inline styles (use CSS instead)
  • Don't include script tags (use JavaScript field)
  • Don't use deprecated HTML

Liquid Best Practices

✅ Do:

  • Use proper Liquid syntax
  • Check if objects exist before using
  • Use filters appropriately
  • Test with different data

❌ Don't:

  • Don't assume data always exists
  • Don't use complex logic (keep it simple)
  • Don't access restricted objects

CSS Best Practices

✅ Do:

  • Use specific class names (e.g., .custom-widget-1)
  • Scope styles to avoid conflicts
  • Use CSS variables when possible
  • Test on different screen sizes

❌ Don't:

  • Don't use generic class names
  • Don't override theme styles unnecessarily
  • Don't use !important unless necessary
  • Don't forget mobile styles

JavaScript Best Practices

✅ Do:

  • Wait for DOM to load (DOMContentLoaded)
  • Use event delegation when possible
  • Handle errors gracefully
  • Test in different browsers

❌ Don't:

  • Don't use global variables unnecessarily
  • Don't conflict with theme scripts
  • Don't forget to clean up event listeners
  • Don't block page rendering

Security Best Practices

Code Validation

  • Validate HTML: Ensure valid markup
  • Sanitize inputs: Don't trust user input
  • Escape output: Use proper escaping in Liquid
  • Test thoroughly: Test all code paths

External Code

  • Only trusted sources: Only use code from trusted sources
  • Review code: Understand what code does before adding
  • Keep updated: Update third-party code regularly
  • Monitor: Watch for security issues

Data Access

  • Minimal access: Only access data you need
  • Check permissions: Ensure you have access to data
  • Protect sensitive data: Don't expose sensitive information

Examples

Example 1: Simple HTML Widget

HTML:

<div class="custom-banner">
  <h3>Special Offer</h3>
  <p>Get 20% off your first order!</p>
</div>

CSS:

.custom-banner {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: 30px;
  text-align: center;
  border-radius: 8px;
}

Example 2: Customer Greeting (Liquid)

Liquid:

{% if customer %}
  <div class="customer-greeting">
    <p>Welcome back, {{ customer.first_name }}!</p>
    {% if customer.orders_count > 0 %}
      <p>You have {{ customer.orders_count }} order(s).</p>
    {% endif %}
  </div>
{% endif %}

Example 3: Interactive Button (JavaScript)

HTML:

<button id="custom-button" class="custom-btn">Click Me</button>
<div id="custom-result"></div>

JavaScript:

document.addEventListener('DOMContentLoaded', function() {
  const button = document.getElementById('custom-button');
  const result = document.getElementById('custom-result');
  
  if (button && result) {
    button.addEventListener('click', function() {
      result.textContent = 'Button clicked!';
    });
  }
});

Example 4: Embedded Widget

HTML:

<div id="widget-container"></div>

JavaScript:

// Third-party widget initialization
(function() {
  // Widget code here
})();

Troubleshooting

Code Not Working

  • Check: Verify code syntax is correct
  • Check: Check browser console for errors
  • Check: Ensure code is in the correct field (HTML vs JavaScript)
  • Check: Test in different browsers

CSS Not Applying

  • Check: Verify CSS selector is correct
  • Check: Check for CSS conflicts with theme styles
  • Check: Use more specific selectors
  • Check: Inspect element to see if styles are applied

JavaScript Errors

  • Check: Open browser console (F12) to see errors
  • Check: Ensure DOM is loaded before running code
  • Check: Verify element IDs/classes exist
  • Check: Check for conflicts with theme scripts

Liquid Not Rendering

  • Check: Verify Liquid syntax is correct
  • Check: Ensure objects exist (use if statements)
  • Check: Check for typos in object names
  • Check: Test with simple Liquid first

Code Breaking Site

  • Solution: Remove the custom code section
  • Solution: Check browser console for errors
  • Solution: Restore from backup if needed
  • Solution: Test code in isolation first

Performance Issues

  • Check: Minimize JavaScript code
  • Check: Optimize CSS (remove unused styles)
  • Check: Defer JavaScript execution
  • Check: Use efficient selectors

When to Use Custom Code

✅ Good Use Cases

  • Third-party widget integration
  • Custom functionality not in theme
  • Advanced Liquid templating
  • Custom styling needs
  • Analytics and tracking

❌ Avoid When

  • Standard sections can do it
  • You're not comfortable with code
  • Code is from untrusted sources
  • You need quick solutions
  • You want easy maintenance

Alternatives to Custom Code

Before Using Custom Code, Consider:

  • Standard sections: Check if a standard section can do it
  • Theme settings: Some customization may be in theme settings
  • Snippets: Create reusable snippets instead
  • Developer help: Hire a developer for complex needs

Getting Help

Resources

  • Shopify Liquid Documentation: shopify.dev/docs/api/liquid
  • HTML/CSS/JavaScript: MDN Web Docs
  • Theme Development: Shopify theme development guides

Support

  • Developer: Hire a Shopify developer for complex needs
  • Community: Shopify Community forums
  • Documentation: Theme and Shopify documentation

Related Sections

  • Rich Text - Text content without code
  • Image with Text - Image and text layouts
  • Custom snippets - Reusable code components

Next Steps:

  • Learn about Rich Text Section
  • Review Shopify Liquid documentation
  • Test code in a development environment first

Remember: Always test custom code thoroughly and backup your theme before making changes!