Skip to main content

shopify-media
component

Accepts a reference to an Image or Media reference and generates an image or video element with srcset and sizes attributes. This component must be a child of a shopify-context component. It takes a query attribute that defines the context it's a part of, and the field to query.

If you want the media to automatically change based on which variant is selected on the variant-selector component, make sure to reference the product image on the product.selectedOrFirstAvailableVariant.image field.

See the playground for more complete examples.

Note

When rendering an image, the media component uses the unpic-img element internally, so you can also pass height, width, layout, aspect-ratio, priority, breakpoints, and sizes attributes to control the scale and size of the image. Learn more about image props in the Unpic documentation.

Anchor to attributesAttributes

Anchor to aspectRatio
aspectRatio
number
required

Instead of providing a width and height, you can provide an aspect ratio. This is passed to the `aspectRatio` attribute of an underlying `unpic-img` element.

Anchor to height
height
number
required

The height of the image. Required, unless width is provided with an aspectRatio.

Anchor to query
query
string
required

Defines the context to reference and field to query. For example, query="product.featuredImage" queries the title of the product featured image, and query="product.selectedOrFirstAvailableVariant.image" queries the image of a specific product variant based on the shopify-variant-selector component.

Anchor to width
width
number
required

The width of the image. Required, unless height is provided with an aspectRatio.

Anchor to breakpoints
breakpoints
string

The breakpoints of the image. This is passed to the breakpoints attribute of an underlying `unpic-img` element.

Anchor to layout
layout
"fixed" | "constrained" | "fullWidth"

The resizing behavior of the image. This is passed to the layout attribute of an underlying `unpic-img` element.

Anchor to priority
priority
boolean

Whether to prioritize the image. This is passed to the priority attribute of an underlying `unpic-img` element.

Anchor to role
role
string | null

The accessibility role of the image. This is set automatically by the media component, but you can override it if needed.

Anchor to sizes
sizes
string

The sizes of the image. This is set automatically by the media component, but you can override it if needed.

Anchor to video-autoplay
video-autoplay
boolean

Used for video media. By default, videos autoplay. To disable autoplay, set to video-autoplay="false".

Anchor to video-controls
video-controls
boolean

Used for video media. By default, video controls are shown. To disable them, set to video-controls="false".

Anchor to video-loop
video-loop
boolean

Used for video media. By default, videos loop. To disable looping, set to video-loop="false".

Anchor to video-muted
video-muted
boolean

Used for video media. By default, videos are muted. To enable audio, set to video-muted="false".

Anchor to video-playsinline
video-playsinline
boolean

Used for video media. By default, videos play inline. To disable inline playback, set to video-playsinline="false".

Was this section helpful?

Example

HTML

<shopify-store
store-domain="https://your-store.myshopify.com"
>
</shopify-store>

<!-- The context is bound to the store -->
<shopify-context
type="product"
handle="handle-of-product"
>
<template>
<h1>
<!-- Query the featured image of the product.
Renders an image element -->
<shopify-media
width="200"
height="300"
query="product.featuredImage"
></shopify-media>
</h1>
</template>
</shopify-context>