Media Element Documentation
The Media element is a versatile component that supports both images and self-hosted videos. It replaces the separate image and video elements, providing a unified way to add visual content to your layouts.
Overview
The Media element allows you to display either an image or a video within the same element, making it easy to switch between content types without replacing elements.
Supported Content Types
Type | Description |
Image | Static images from Instant or Shopify |
Video | Self-hosted videos (ideally from Shopify content folder) |
Adding the Media Element
Steps
Navigate to the Insert panel in the left sidebar
Hover over Media
A popover appears with the Media element
Drag the Media element onto your canvas
Selecting Content Type
Once the Media element is on your canvas:
Select the Media element
In the right sidebar, locate the Media header
Click on the Content field
A popover appears with Edit media
Use the tabs to switch between Image and Video
Working with Images
With the Image tab selected in the Edit media popover:
Choosing an Image
Click Choose image
Select from available images
Image Sources
Source | Description |
Instant | Images uploaded directly to Instant |
Shopify | Images from your connected Shopify store |
You can switch between sources and search within both views.
Uploading Images
Click the upload option within the popover to add new images to your library.
Dynamic Product Images
When the Media element is inside a container connected to a Shopify product:
Click the database icon next to the Content field
Select from dynamic image options:
Option | Description |
Featured image | The main product image |
Media 1 | First image in the product media gallery |
Media 2 | Second image in the product media gallery |
Media 3 | Third image in the product media gallery |
These images update automatically based on the connected product.
Working with Videos
With the Video tab selected in the Edit media popover:
Adding a Video
Insert the video link in the provided field
Ideally, host your video in your Shopify content folder and paste the URL
Thumbnail Image
Upload a thumbnail (poster image) that displays:
Before the video plays
When video playback is blocked
As a fallback if the video cannot load
Recommendation: Always upload a thumbnail for videos to ensure a good user experience. Autoplay cannot be guaranteed due to various device settings such as energy saver mode. This makes the Thumbnail essential.
Autoplay Options
Option | Behavior |
On | Video attempts to autoplay when loaded |
Off | Video waits for user interaction |
Loop | Video autoplays and repeats continuously |
Controls
When autoplay is set to Loop, you can choose to show or hide video controls.
Dynamic Product Videos
Click the database icon next to Content to link directly to a video from your product configuration.
Media Sizing Options
Fit vs Fill
Under the Media header, choose how your content behaves within the element:
Mode | Behavior |
Fit | Content scales to fit entirely within the element without cropping. If proportions differ, empty space appears on the sides. |
Fill | Content scales to completely fill the element, cropping any overflow. |
Example
For a 500x500 pixel Media element with a 500x200 pixel image:
Mode | Result |
Fit | Image scales to touch top and bottom, empty space on left and right |
Fill | Image scales to fill sides, top and bottom are cropped |
Focus Point
For images larger than the Media element, set a focal point to control which part of the image remains visible.
Setting a Focus Point
Click on Focus in the right sidebar
A popover opens with your image
Click to set the focal point
The image will crop around this point when using Fill mode
Image Quality
Control the quality and file size of rendered images for SEO and performance optimization.
Quality Options
Setting | Description |
Auto | Balanced between performance and quality (recommended) |
Thumbnail | Smallest file size |
Small | Low resolution |
Medium | Standard resolution |
Large | High resolution |
Very Large | Higher resolution |
Ultra Large | Maximum quality, largest file size |
Note: Higher quality settings result in larger file sizes, which may affect page load speed.
Element Dimensions
The Media element can be resized like any other element. Access sizing controls in the right sidebar under Size.
Available Size Options
Option | Description |
Width | Set the element width |
Height | Set the element height |
Min Width | Minimum width constraint |
Max Width | Maximum width constraint |
Min Height | Minimum height constraint |
Max Height | Maximum height constraint |
Quick Reference
Task | Location |
Insert Media element | Insert panel → Media |
Switch to image | Content → Edit media → Image tab |
Switch to video | Content → Edit media → Video tab |
Choose image | Edit media → Image → Choose image |
Add video link | Edit media → Video → Paste URL |
Use Shopify images | Choose image → Switch to Shopify tab |
Use dynamic product media | Click database icon → Select media type |
Set fit/fill mode | Right sidebar → Media → Fit/Fill |
Set focus point | Right sidebar → Focus |
Set image quality | Right sidebar → Quality |
Add video thumbnail | Edit media → Video → Upload thumbnail |
Set autoplay | Right sidebar → Autoplay |
Content Type Comparison
Feature | Image | Video |
Static content | ✓ | ✓ |
Dynamic product content | ✓ | ✓ |
Fit/Fill sizing | ✓ | ✓ |
Focus point | ✓ | ✗ |
Quality settings | ✓ | ✗ |
Autoplay options | ✗ | ✓ |
Thumbnail/poster | ✗ | ✓ |
Loop option | ✗ | ✓ |