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".

MediaAttributes

aspectRatio
Instead of providing a width and height, you can provide an aspect ratio. This is passed to the [\`aspectRatio\`](https://unpic.pics/img/webc/#aspect-ratio) attribute of an underlying \`unpic-img\` element.
```
number
```
breakpoints
The breakpoints of the image. This is passed to the [breakpoints](https://unpic.pics/img/webc/#breakpoints) attribute of an underlying \`unpic-img\` element.
```
string
```
height
The height of the image. Required, unless width is provided with an aspectRatio.
```
number
```
layout
The resizing behavior of the image. This is passed to the [layout](https://unpic.pics/img/webc/#layout) attribute of an underlying \`unpic-img\` element.
```
"fixed" | "constrained" | "fullWidth"
```
priority
Whether to prioritize the image. This is passed to the [priority](https://unpic.pics/img/webc/#priority) attribute of an underlying \`unpic-img\` element.
```
boolean
```
query
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.
```
string
```
role
The accessibility role of the image. This is set automatically by the media component, but you can override it if needed.
```
string | null
```
sizes
The sizes of the image. This is set automatically by the media component, but you can override it if needed.
```
string
```
video-autoplay
Used for video media. By default, videos [autoplay](https://developer.mozilla.org/docs/Web/HTML/Element/video#autoplay). To disable autoplay, set to `video-autoplay="false"`.
```
boolean
```
video-controls
Used for video media. By default, [video controls](https://developer.mozilla.org/docs/Web/HTML/Element/video#controls) are shown. To disable them, set to `video-controls="false"`.
```
boolean
```
video-loop
Used for video media. By default, videos [loop](https://developer.mozilla.org//docs/Web/HTML/Element/video#loop). To disable looping, set to `video-loop="false"`.
```
boolean
```
video-muted
Used for video media. By default, videos are [muted](https://developer.mozilla.org/docs/Web/HTML/Element/video#muted). To enable audio, set to `video-muted="false"`.
```
boolean
```
video-playsinline
Used for video media. By default, videos [play inline](https://developer.mozilla.org/docs/Web/HTML/Element/video#playsinline). To disable inline playback, set to `video-playsinline="false"`.
```
boolean
```
width
The width of the image. Required, unless height is provided with an aspectRatio.
```
number
```

interface MediaAttributes {
  /** 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. */
  query: string;
  /**
   * The height of the image. Required, unless width is provided with an aspectRatio.
   */
  height: number;
  /**
   * The width of the image. Required, unless height is provided with an aspectRatio.
   */
  width: number;
  /**
   * Instead of providing a width and height, you can provide an aspect ratio. This is passed to the [\`aspectRatio\`](https://unpic.pics/img/webc/#aspect-ratio) attribute of an underlying \`unpic-img\` element.
   */
  aspectRatio: number;
  /**
   * Whether to prioritize the image. This is passed to the [priority](https://unpic.pics/img/webc/#priority) attribute of an underlying \`unpic-img\` element.
   */
  priority?: boolean;
  /**
   * The accessibility role of the image. This is set automatically by the media component, but you can override it if needed.
   */
  role?: string | null;
  /**
   * The breakpoints of the image. This is passed to the [breakpoints](https://unpic.pics/img/webc/#breakpoints) attribute of an underlying \`unpic-img\` element.
   */
  breakpoints?: string;
  /**
   * The sizes of the image. This is set automatically by the media component, but you can override it if needed.
   */
  sizes?: string;
  /**
   * The resizing behavior of the image. This is passed to the [layout](https://unpic.pics/img/webc/#layout) attribute of an underlying \`unpic-img\` element.
   */
  layout?: "fixed" | "constrained" | "fullWidth";

  /**
   * Used for video media. By default, [video controls](https://developer.mozilla.org/docs/Web/HTML/Element/video#controls) are shown. To disable them, set to `video-controls="false"`.
   */
  "video-controls"?: boolean;
  /**
   * Used for video media. By default, videos [autoplay](https://developer.mozilla.org/docs/Web/HTML/Element/video#autoplay). To disable autoplay, set to `video-autoplay="false"`.
   */
  "video-autoplay"?: boolean;
  /**
   * Used for video media. By default, videos are [muted](https://developer.mozilla.org/docs/Web/HTML/Element/video#muted). To enable audio, set to `video-muted="false"`.
   */
  "video-muted"?: boolean;
  /**
   * Used for video media. By default, videos [loop](https://developer.mozilla.org//docs/Web/HTML/Element/video#loop). To disable looping, set to `video-loop="false"`.
   */
  "video-loop"?: boolean;
  /**
   * Used for video media. By default, videos [play inline](https://developer.mozilla.org/docs/Web/HTML/Element/video#playsinline). To disable inline playback, set to `video-playsinline="false"`.
   */
  "video-playsinline"?: boolean;
}

Was this section helpful?

Example

HTML

<shopify-store

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

</shopify-store>

<shopify-context

type="product"

handle="handle-of-product"

<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>

examples

example

description

This is the default 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>

shopify-mediacomponent

Anchor to attributesAttributes

MediaAttributes

examples

example

description

HTML

shopify-media
component