VTEX Developer Portal

📢 Use this project, contribute to it or open issues to help evolve it using Store Discussion.

Store Media

All ContributorsAll Contributors

The Media app allows you to display image and video assets using a single block.

media-list-examplemedia-list-example

Configuration

  1. Add the store-media app to your theme's dependencies in the manifest.json file:
 "dependencies ": {
+  "vtex.store-media": "0.x"
 }

Now, you are able to use all blocks exported by the store-media app. Check out the full list below:

Block nameDescription
mediaThis block is capable of displaying a single image or video.
list-context.media-listThis block allows you to display a list of images and videos in your store with a higher degree of composability. You can use it along with other list-context or slider-layout blocks to create different sliders and layouts.

media block

The media block inherits all props from image and video blocks. It's highly recommended you check out the docs for Image and Video blocks before using this block.

You can use props from both blocks, but media will only consider the props from the block (image or video) that matches the current mediaType, or, in the case of mediaType being imageOrVideo, that matches the type of the src.

Prop nameTypeDescriptionDefault value
mediaTypeenumType of the media to be displayed. Possible values are: image (behaves as an image block no matter the src), video (behaves as an video block no matter the src), and imageOrVideo. Choosing imageOrVideo will make media automatically identify the type of the src based on its extension and behave accordingly.imageOrVideo

Use the admin's Site Editor to manage some props declared in the media block. Using the Site Editor to provide the image or video src will force you to choose between image and video.

Usage Example:

"media#mobile-phone": {
  "props": {
    "src": "https://storecomponents.vteximg.com.br/arquivos/mobile-phone.png",
    "blockClass": "storePrint"
  }
}

list-context.media-list block

The list-context.media-list block acts just like the list-context.image-list block and inherits a lot from image and video blocks, with a few key differences. It's highly recommended you check out the docs for Image and Video blocks before using this block.

list-context.media-list accepts both images and videos, so you can mix them inside a single carousel, for example. Images can receive image blocks' props and videos can receive video blocks' props. If you pass props that don't match the media type, they will be ignored.

Prop nameTypeDescriptionDefault value
height`stringnumber`This value is used for the max-height CSS property and is applied to images only.
mediaList[MediaListElement]List of MediaListElement that represents the media to be added to the list context.[]
  • MediaListElement object

A MediaListElement object has a very similar shape to the props accepted by the media component, that is, you can specify the mediaType of the asset you want to display and pass the props for image and video blocks. Read the docs for the media block to better understand how that works.

Differently from the media component, it does not use the src prop to receive the assets. For images, it uses the image and mobileImage props, and, for video, it uses the video and mobileVideo props.

Prop nameTypeDescriptionDefault value
imagestringURL to the image to be displayed.undefined
mobileImagestringURL to the image to be displayed when the user is using a mobile device. If it's undefined, image will be used instead.undefined
videostringURL to the video to be displayed.undefined
mobileVideostringURL to the video to be displayed when the user is using a mobile device. If it's undefined, video will be used instead.undefined

Usage Example:

"list-context.media-list#demo": {
  "children": ["slider-layout#demo-media"],
  "props": {
    "height": 720,
    "mediaList": [
      {
        "image": "https://storecomponents.vteximg.com.br/arquivos/banner-principal.png",
        "mobileImage": "https://storecomponents.vteximg.com.br/arquivos/banner-principal-mobile.jpg"
      },
      {
        "video": "https://www.youtube.com/embed/JgkrlaF52WQ"
      },
      {
        "image": "https://storecomponents.vteximg.com.br/arquivos/banner.jpg",
        "mobileImage": "https://storecomponents.vteximg.com.br/arquivos/banner-principal-mobile.jpg"
      }
    ]
  }
},
"slider-layout#demo-media": {
  "props": {
    "itemsPerPage": 1,
    "infinite": true,
    "showNavigationArrows": "desktopOnly",
    "blockClass": "carousel"
  }
}

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

Just like they do with props, all blocks from this app inherits all of image and video blocks' CSS Handles. You can find them in their respective docs.

Keep in mind that, for instance, applying CSS customizations to CSS Handles that came from image won't have any effect if the mediaType is set to video or if the mediaType is set to imageOrVideo and the src was identified as a video.

Contributors ✨

Thanks goes to these wonderful people:

This project follows the all-contributors specification. Contributions of any kind are welcome!

Updated 8 months ago


Store Media


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.