All Tutorials

Adding Media to themes

All Tutorials

Adding Media to themes

Adding Media to themes

You can add media such as 3D models, embedded videos, and Vimeo or YouTube videos to your theme's product pages. 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 using a array and the media Liquid object.

You can also use the GraphQL Admin API to manage the various types of media associated with products. You can find more information about the different types of product media, and how to use Shopify's API to work with them, in the working with product media API guide.

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 Vimeo or YouTube video by clicking Add media from URL > Embed 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 | external_video_tag }}
      {% when 'video' %}
        <div class="product-single__media" data-media-id="{{ }}">
          {{ media | video_tag: controls: true }}
      {% when 'model' %}
        <div class="product-single__media" style="padding-top: 100%" data-media-id="{{ }}">
          {{ media | model_viewer_tag }}
      {% else %}
        <div class="product-single__media" style="padding-top: 100%;" data-media-id="{{ }}">
          {{ media | media_tag }}
    {% 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 %}
      {% 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.


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.


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 > 1 %}
    <div class="thumbnails-wrapper">
      {% for media in %}
        <a data-thumbnail-id="{{ }}">
          <img class="product-single__thumbnail-image" src="{{ media | img_url: '110x110', scale: 2 }}" alt="{{ media.alt }}">
      {% endfor %}
  {% 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="{{ }}" class="grid-view-item__image" alt="{{ product.featured_media.alt }}" src="{{ product.featured_media | img_url }}">

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 == 'product' %}
      {%- assign og_title = product.title | strip_html -%}
      {%- assign og_type = 'product' -%}
      {% if > 0 %}
        {%- capture og_image_tags -%}{% for media in limit:3 -%}<meta property="og:image" content="http:{{ media | img_url: '1200x1200' }}">{% endfor -%}{% endcapture -%}
        {%- capture og_image_secure_url_tags -%}{% for media in 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:

  function setupShopifyXr(){
    if (!window.ShopifyXR) {
      document.addEventListener('shopify_xr_initialized', function() {
      {% assign models = | where: 'media_type', 'model' | json %}
      window.ShopifyXR.addModels({{ models }});

      name: 'shopify-xr',
      version: '1.0',
      onLoad: setupShopifyXr

To launch an XR experience from a DOM element on your page, add the data-shopify-xr data attribute and the 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.

{% assign first_3d_model = | where: "media_type", "model" | first %}

  data-shopify-model3d-id="{{ }}"
  data-shopify-title="{{ product.title | escape }}"

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

  model3dId: 1,
  title: "{{ product.title | escape }}",

How do I make videos autoplay, loop, or play with muted audio?

For videos that you've uploaded, you can control these behaviors by passing the following parameters to the video_tag and media_tag filters:

  • autoplay
  • loop
  • mute

Each of these parameters is a boolean value, and all of them are false by default. You can set them to true in any combination:

// Example: autoplay a video
{{ myvideo | video_tag: autoplay: true }}
// Example: autoplay a video, but start with muted audio
{{ myvideo | video_tag: autoplay: true, mute: true }}

You can control these behaviors for external videos using the external_video_url filter. The available parameters depend on the video host.