Skip to main content

Support product media

Merchants can add media to their products, like images, 3D models, videos, and YouTube or Vimeo videos.

In this tutorial, you'll learn how to support product media in your theme.

Anchor to ResourcesResources

Anchor to Implementing product mediaImplementing product media

Product media is usually displayed on the product page. However, you might want to display product media in other areas of your theme, so it's recommended to build your media display in a snippet so that it can be reused.

To display product media, you can loop through the media attribute of the product object and apply the associated media filter, depending on the media type.

Anchor to ExampleExample

If you want to output product media on the product page, and your product page content is hosted in a product.liquid section, then you might do the following:

  • Create a snippet called media.liquid to host your media display.
  • Render media.liquid in your product.liquid section.

sections/product.liquid

{% for media in product.media %}
{% render 'media', media: media %}
{% endfor %}

snippets/media.liquid

{% case media.media_type %}
{% when 'image' %}
<div className="product-single__media" style={{paddingTop: '{{ 1 | divided_by'}} data-media-id="{{ media.id }}">
{{ media | image_url: width: 2048, height: 2048 | image_tag }}
</div>
{% when 'external_video' %}
<div className="product-single__media" style={{paddingTop: '{{ 1 | divided_by'}} data-media-id="{{ media.id }}">
{{ media | external_video_tag }}
</div>
{% when 'video' %}
<div className="product-single__media" data-media-id="{{ media.id }}">
{{ media | video_tag: controls: true }}
</div>
{% when 'model' %}
<div className="product-single__media" style={{paddingTop: '100%'}} data-media-id="{{ media.id }}">
{{ media | model_viewer_tag }}
</div>
{% else %}
<div className="product-single__media" style={{paddingTop: '100%'}} data-media-id="{{ media.id }}">
{{ media | media_tag }}
</div>
{% endcase %}

Each media type in the example above is wrapped in a <div> element with custom style and data attributes. These are based on the considerations documented in UX considerations, and should be adjusted accordingly to match your approach.

Tip

For another example of supporting media in a theme, you can refer to Dawn's implementation in the main-product.liquid section and product-thumbnail.liquid snippet.

Anchor to UX considerationsUX considerations

Every theme requires a different approach to create responsive media that works across all screen sizes and devices. The following general recommendations can help ensure that you're offering a good customer experience:

A product can have multiple videos, so if your theme has a thumbnail view for each media element, or displays multiple media elements at once, you should ensure that only the active video is playing.

Tip

For more in-depth information, refer to Product media UX guidelines.

Anchor to Responsive media elementsResponsive media elements

Shopify-hosted 3D models use Google's model viewer component, and externally rendered videos are rendered in <iframe> elements. Neither of these are responsive containers by default.

Shopify-hosted videos are rendered in HTML5 video players, which are responsive by default, however only once they're rendered.

Given the above, you should consider using an aspect ratio box to create a responsive container for each.

Tip

3D models don't have predefined aspect ratios, so it's common practice to create a square container by setting padding-top to 100%.

Anchor to Interactive media elementsInteractive media elements

Shopify-hosted, and externally-hosted, video elements, and 3D models have interactive components. For example, videos have progress bars and volume control, and 3D models can be rotated.

If any of these media elements are hosted in a carousel or swipe-interactive display, then the interactive components shouldn't interfere with the ability to interact with the display.

Anchor to Use media preview imagesUse media preview images

Every media type has a preview_image attribute. This could be useful in scenarios like the following:

Tip

Applying the image_url Liquid URL filter to the media object returns the preview_image URL.

Anchor to Product thumbnailsProduct thumbnails

If your theme displays thumbnails for each media source on the product, then you can utilize the preview_image attribute of the media object in order to show a thumbnail image for each media source.

For example:

{% if product.media.size > 1 %}
<div className="thumbnails-wrapper">
{% for media in product.media %}
<a data-thumbnail-id="{{ media.id }}">
{{ media.preview_image | image_url: width: 110, height: 110, scale: 2 | image_tag: media.alt, 'product-single__thumbnail-image' }}
</a>
{% endfor %}
</div>
{% endif %}
Tip

The above example adds a data-thumbnail-id attribute which is intended to be used in conjunction with the data-media-id attribute that's included in the general media loop example above. This gives you an easy way to associate a thumbnail with its media display.

Anchor to Social media imagesSocial media images

Rather than only showing images for social media previews, you can include media preview images as well.

For example:

{%- 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 | image_url: width: 1200 height: 1200 }}" />
{%- endfor %}
{%- endcapture -%}

{%- capture og_image_secure_url_tags -%}
{% for media in product.media limit:3 -%}
<meta property="og:image:secure_url" content="https:{{ media | image_url: with: 1200, height: 1200 }}" />
{%- endfor %}
{%- endcapture -%}
{%- endif -%}
{%- endif -%}

Anchor to Support AR functionalitySupport AR functionality

If merchants have 3D models of their products, then you can give them the option to showcase those models through AR. To do this, you can use the Shopify-XR library to support AR Quick Look in iOS's Safari, and Android's Scene Viewer.

You need to do the following to use this library:

Anchor to Initialize the libraryInitialize the library

The following JavaScript needs to be included on product pages to initialize the library:

<script>
function setupShopifyXr(){
if (!window.ShopifyXR) {
document.addEventListener('shopify_xr_initialized', function() {
setupShopifyXr();
});
}else{
{% assign models = product.media | where: 'media_type', 'model' | json -%}
window.ShopifyXR.addModels({{ models }});
window.ShopifyXR.setupXRElements();
}
}

window.Shopify.loadFeatures([
{
name: 'shopify-xr',
version: '1.0',
onLoad: setupShopifyXr
}
]);
</script>

Anchor to Launch the displayLaunch the display

You can launch the display in two ways:

Anchor to Launch the display with a buttonLaunch the display with a button

You can launch the display with a button that has the following attributes:

AttributeDescription
data-shopify-xrThe Shopify-XR library scans the DOM for elements with this attribute and attaches a click handler to launch the display.
data-shopify-model3d-idThe media ID of the current model.
data-shopify-titleThe title of the product.
data-shopify-xr-hiddenA base data attribute for the Shopify-XR library to reference.

You would include a button for each model type media source.

For example:

{% for media in product.media %}
{% case media.type %}
...
{% when 'model' %}
<div className="product-single__media" style={{paddingTop: '100%'}} data-media-id="{{ media.id }}">
{{ media | model_viewer_tag }}
</div>

<button
data-shopify-xr
data-shopify-model3d-id="{{ media.id }}"
data-shopify-title="{{ product.title | escape }}"
data-shopify-xr-hidden
/>
...
{% endcase %}
{% endfor %}

Anchor to Launch the display with JavaScriptLaunch the display with JavaScript

Rather than include a button to launch the display, you can use JavaScript. For example:

<script>
window.ShopifyXR.launchXR({
model3dId: [media-id],
title: "{{ product.title | escape }}",
});
</script>
Note

In the example above, [media-id] represents the media ID for the associated model.

Anchor to Control video functionality with parametersControl video functionality with parameters

Shopify hosted videos can have all HTML5 video attributes set when they're rendered with the Liquid video_tag or media_tag filter. For example:

  • autoplay - Whether to automatically play the video after it's loaded.
  • loop - Whether to loop the video.
  • muted - Whether to mute the video's audio.
  • controls - Whether a user can control the video playback.

Each parameter is false by default, however you can set them to be true like the following:

<!-- Autoplay a video -->
{{ media | video_tag: autoplay: true }}

<!-- Autoplay a video, and loop it -->
{{ media | video_tag: autoplay: true, loop: true }}

<!-- Autoplay a video, loop it, and mute it -->
{{ media | video_tag: autoplay: true, loop: true, muted: true }}

<!-- Autoplay a video, loop it, mute it, and allow the user to control the video playback -->
{{ media | video_tag: autoplay: true, loop: true, muted: true, controls: true }}
Tip

You can control these same behaviors for externally-hosted videos using the Liquid external_video_url filter. However, the available parameters depend on the video host.

Was this page helpful?