Adding Media to themes

You can add Media such as 3D models, embedded videos, and YouTube videos to your theme's product pages. But before you can display these types of media, you need to update your theme to support them. This guide explains how to display Media on your product page.

Step 1: Add media to your product

Before adding media to your theme, you need to add one of each media type to your product.

  1. From your Shopify admin, go to Products and click Add product.

  2. Enter a product title.

  3. In the Media section, add one of each media type by dragging and dropping them from your desktop to the drop zone. You can also add a YouTube video by clicking Add media from URL > Embed Youtube Video, and then pasting the link to the video that you want.

Step 2: Identify the existing image loop

Before adding other media types, you need to identify the code in your theme that displays your product image.

  1. Open the product-template found in the Sections directory.

  2. Find the image loop that displays your themes main images.

This code will be used in the Create a new liquid snippet section of these instructions.

Step 3: Create a new Liquid snippet

A new Liquid snippet will be used to display all four media types in the main gallery of the page. In this step we will create the snippet and the default code for each media type.

  1. On the left side, click on the Snippets heading to reveal your Snippets content.
  2. Under the Snippets heading, click on the Add a new snippet link:
  1. Call your new snippet media. Click Create snippet.

  2. Copy and paste the following code into your new media.liquid file.

    {% case media.media_type %}
      {% when 'image' %}
      {% when 'external_video' %}
        <div class="product-single__media" style="padding-top: {{ 1 | divided_by: media.aspect_ratio | times: 100}}%;" data-media-id="{{ media.id }}">
          {{ media | external_video_tag }}
        </div>
      {% when 'video' %}
        <div class="product-single__media" data-media-id="{{ media.id }}">
          {{ media | video_tag: controls: true }}
        </div>
      {% when 'model' %}
        <div class="product-single__media" style="padding-top: 100%" data-media-id="{{ media.id }}">
          {{ media | model_viewer_tag }}
        </div>
      {% else %}
        <div class="product-single__media" style="padding-top: 100%;" data-media-id="{{ media.id }}">
          {{ media | media_tag }}
        </div>
    {% endcase %}
  1. Add the image loop code that you identified earlier (excluding the for loop) in between the {% when 'image' %} and {% when 'external_video' %} tags.

  2. Replace all of the image loop code that you identified earlier in the product section with the following code:

    {% for media in product.media %}
      {% include 'media' %}
    {% endfor %}
  1. Save your changes.

Custom styles for your theme

Every theme requires different styles to create responsive media that work across all screen sizes and devices. The following recommendations can help to make sure that you're offering a good customer experience.

Shopify-hosted videos

Shopify-hosted videos are rendered in a HTML5 video player by default. The HTML5 player is responsive and doesn't require any specific customizations.

If you're using Shopify-hosted videos, then you should consider the following guidelines:

  • Consider using an aspect ratio box to create a responsive container for the video to be placed prior to loading.
  • On themes that use image carousels or swiping, the navigation of the progress bar or volume controls should not interfere with the ability to swipe or scroll through media or the page.

3D models

Shopify-hosted 3D models use Google’s model-viewer component. This isn't a responsive container by default, and it should be modified to support a responsive experience.

We recommend using an aspect ratio box to contain the model-viewer component. Since models don't have predefined aspect ratios, it's recommend that you create a square container by setting padding-top to 100%. On themes that use image carousels or swiping, the rotation of the model should not interfere with the ability to swipe or scroll through media or the page.

External videos

Videos that are hosted outside of Shopify render inside an iFrame. By default, iFrames are not responsive. This means that you need to take extra steps to make them responsive across all screen sizes and devices.

  • We recommend using an aspect ratio box to create a responsive container for the iFrame to be placed in.
  • On themes that use image carousels or swiping, the navigation of the progress bar or volume controls should not interfere with the ability to swipe or scroll through media or the page.

Custom JavaScript for your theme

Each theme requires different events depending on its layout. Keep the following recommendations in mind when adding media to your theme.

Video

When a product has more than one video, their audio tracks can cause problems for customers on your site. This applies to both Shopify-hosted videos and external videos.

  • If your theme has a thumbnail gallery, then we recommend that when a video is hidden from view it should be paused.
  • If your theme displays multiple media at once, then we recommend that when one video is started any other videos playing should be paused.

3D models

On page load, the <head> will call the Shopify.detectLoadJS library. This evaluates whether the model-viewer component should be loaded. Sometimes the <head> will be evaluated before the model_viewer_tag is rendered. In these cases, window.Shopify.detectLoadJS() should be called to load the model-viewer library.

For example, when a new featured product section is added to the homepage in the theme editor, the <head> would have been evaluated prior to the change and the model-viewer library would not be loaded. To fix this, the model-viewer should be loaded by calling window.Shopify.detectLoadJS().

FAQ

My theme has thumbnail images for each image. How do I ensure all media types are displayed as well?

Every media type has a preview_image attribute. It's a good idea to replace your existing image loop that displays the thumbnails with a media loop. The thumbnail example below contains the required changes.

In the examples above, the media containers have a data-media-id=. We recommend using this tag to match to each variant thumbnail in the JavaScript.

  {% if product.media.size > 1 %}
    <div class="thumbnails-wrapper">
      {% for media in product.media %}
        <a data-thumbnail-id="{{ media.id }}">
          <img class="product-single__thumbnail-image" src="{{ media.preview_image | img_url: '110x110', scale: 2 }}" alt="{{ media.alt }}">
        </a>
      {% endfor %}
    </div>
  {% endif %}

How do I modify my collection grids to show media?

Products now have a featured_media attribute that selects the first media on the product. We recommend using featured_media to display the preview image on your theme's collection grid. The grid item example below contains the required changes.

    <div class="grid-view-item">
      <a class="grid-view-item__link" href="{{ product.url }}">
        <span class="visually-hidden">{{ product.title }}</span>
        <img id="{{ product.featured_media.id }}" class="grid-view-item__image" alt="{{ product.featured_media.alt }}" src="{{ product.featured_media | img_url }}">
      </a>
    </div>

How do I update my theme to display the new media attributes on social media?

Themes generally use meta tags to share information on social media about what images are available on a product page. The images loop should be replaced with a media loop. The meta tag example below contains the required changes.

    {% if template.name == 'product' %}
      {%- assign og_title = product.title | strip_html -%}
      {%- assign og_type = 'product' -%}
      {% if product.media.size > 0 %}
        {%- capture og_image_tags -%}{% for media in product.media limit:3 -%}<meta property="og:image" content="http:{{ media | img_url: '1200x1200' }}">{% endfor -%}{% endcapture -%}
        {%- capture og_image_secure_url_tags -%}{% for media in product.media limit:3 -%}<meta property="og:image:secure_url" content="https:{{ media | img_url: '1200x1200' }}">{% endfor -%}{% endcapture -%}
      {% endif %}
    {% endif %}

How do I add AR functionality to my theme?

You can use the Shopify-XR library to add AR Quick Look on iOS Safari and Scene Viewer on Android to your themes. The Shopify-XR library is initialized with the 3D models on your product page, and can be launched by using a button or through JavaScript.

To set up the library, add the following script to your product template:

<script>
window.ShopifyXR=window.ShopifyXR||function(){(ShopifyXR.q=ShopifyXR.q||[]).push(arguments)}

  ShopifyXR('setModels', );
</script>
<script defer src="https://cdn.shopify.com/shopifycloud/shopify-xr-js/assets/v1.0/shopify-xr.en.js"></script>

To launch an XR experience from a DOM element on your page, add the data-shopify-xr data attribute and the media.id associated with the 3D model you want to display. Shopify XR scans any elements that have the data-shopify-xr attribute and attaches the XR click handler that is supported by the browser's platform.

<button
  data-shopify-xr
  data-shopify-model3d-id=""
  data-shopify-title=""
  style="display: none;"
/>

Shopify XR's functionality can also be launched by using the following JavaScript:

<script>
window.ShopifyXR.launchXR({
  model3dId: 1,
  title: "",
});
</script>

Ready to start selling with Shopify?

Try it free