How to Detect Shopify Theme Preview Mode

Introduction

Shopify theme developers and store owners often need to differentiate between the live store environment and the theme preview mode. This distinction is crucial for implementing features that should only be visible during development or testing. In this comprehensive guide, we’ll explore various methods to detect Shopify’s theme preview mode, ensuring your theme behaves correctly in different contexts.

Understanding Shopify’s Theme Preview Mode

What is Theme Preview Mode?

Theme preview mode is a feature in Shopify that allows developers and store owners to view and test changes to their store’s theme without affecting the live site. It’s an essential tool for development and quality assurance.

Why Detect Preview Mode?

Detecting preview mode enables developers to:

1. Display debugging information
2. Show or hide certain elements
3. Implement features specifically for testing
4. Ensure a smooth transition between development and production environments

The Importance of Accurate Detection

Accurately detecting preview mode is crucial to prevent unintended behavior on the live store. Using reliable methods ensures that your theme functions correctly in all scenarios.

Methods to Detect Shopify Theme Preview Mode

Using Liquid Variables

The request.design_mode Variable

The most current and recommended method to detect theme preview mode is by using the request.design_mode Liquid variable. This variable returns true when the theme is being viewed in the theme editor or preview mode.

Example usage:

{% if request.design_mode %}
  <div class="preview-mode-notice">You are viewing this theme in preview mode</div>
{% endif %}

The request.visual_preview_mode Variable

For more recent Shopify themes, you can also use the request.visual_preview_mode variable. While its exact behavior is not fully documented, it can be useful in certain scenarios.

JavaScript Detection

The Shopify.designMode Property

In JavaScript, you can use the Shopify.designMode property to detect if the theme is being viewed in the theme editor or preview mode.

Example usage:

if (Shopify.designMode) {
  console.log('Theme is in preview mode');
}

Deprecated Methods

Content Header Check (Deprecated)

Previously, developers used a method involving checking the content_for_header for specific strings. However, this method is no longer supported and should be avoided:

{% if content_for_header contains "previewBarInjector.init();" %}
  <!-- Preview mode detected -->
{% endif %}

URL-based Detection (Deprecated)

Another outdated method involved checking the URL for preview-specific domains. This approach is unreliable and not recommended:

{% if request.host contains 'shopifypreview.com' %}
  <!-- Preview mode detected -->
{% endif %}

Best Practices for Implementing Preview Mode Detection

Combining Liquid and JavaScript

For the most robust detection, consider using both Liquid and JavaScript methods:

{% if request.design_mode %}
  <script>
    if (Shopify.designMode) {
      console.log('Theme is in preview mode');
    }
  </script>
{% endif %}

Avoiding False Positives

Be cautious when implementing preview mode detection. Ensure that your logic doesn’t accidentally trigger in production environments.

Regular Updates

Shopify’s platform evolves, so it’s essential to keep your detection methods up-to-date. Regularly check Shopify’s documentation for any changes to preview mode detection.

Use Cases for Preview Mode Detection

Displaying Debug Information

When in preview mode, you might want to display additional information to help with development:

{% if request.design_mode %}
  <div class="debug-info">
    Theme ID: {{ theme.id }}
    Theme Name: {{ theme.name }}
  </div>
{% endif %}

Showing Test Elements

Preview mode is perfect for displaying elements that are still in development:

{% if request.design_mode %}
  <div class="test-banner">New Feature Coming Soon!</div>
{% endif %}

Conditional Styling

You can apply different styles when in preview mode:

{% if request.design_mode %}
  <style>
    .test-element { border: 2px solid red; }
  </style>
{% endif %}

Troubleshooting Preview Mode Detection

Common Issues

1. Inconsistent behavior across devices
2. False positives in production
3. Detection not working in certain sections of the theme

Solutions

1. Use the most up-to-date detection methods
2. Test thoroughly across different devices and browsers
3. Ensure your code is placed correctly within your theme files

Conclusion

Detecting Shopify’s theme preview mode is an essential skill for theme developers. By using the correct methods and following best practices, you can create more robust and flexible themes that behave correctly in both development and production environments. Remember to stay updated with Shopify’s latest documentation and best practices to ensure your detection methods remain effective and reliable.