Examples

Basic Usage

Even though a Media Preview can be used to only display an image, its full potential is leveraged when additionally providing a video clip.

💡 Pro Tip

The Media Preview does playback the video only when it is active . In the example below the Media Preview's active state is controlled by a user's hover gesture.

Best Practices:

Images should always be paired with an alternative text to support assistive technologies.

Mode and Appearance

By default, the Media Preview's background adapts the color to a light environment but can be changed to make it more visible in a dark mode.

💡 Pro Tip

The appearance of a Story Card can be set using the appearance property or by nesting it into a cosmos-mode component. Read more about the Mode & Appearance concept.

Preview Image

To improve the user experience, a Media Preview can display an image preview while waiting for the high-resolution image to be loaded.

Note: The example below demonstrates the rendering of the preview image only. In a production environment, a high-resolution _image_ would be set alongside.

Best Practices:

Image previews should be a down-scaled version of the image. It's common to provide an image that is 10% of its original size.

Image previews should have the same aspect ratio as their original

To ensure meaningful content is shown as fast as possible without any additional network requests preview images should be provided as base64 encoded data URIs

Responsiveness and Performance

A great way to balance client-side performance and responsive images is by using srcset in conjunction with sizes and loading attributes. Read more about responsive image best practices here: Image

Adaptive Sizing

By default, the Media Preview always takes the available width and calculates its height based on the image that is displayed.

But it can adapt to any size when a different dimension is specified while ensuring that the media displayed is covering the available space.

💡Did you know

Grab the handle in the lower-right corner of the container in the example below and see the adaptive sizing behavior of the Media Preview in action.

Best Practices:

Specify a specific size for the Media Preview directly or make it adapt to a container's dimension by setting its height to 100%

Listen to Resize Events

When initially mounting to the DOM and whenever the Media Preview changes its dimensions, it emits a resize the event including the current width and height.

A common use case is to update the image to make it perfectly fit the available space.

Best Practices:

observe-resize has to be enabled in order for the resize event to be emitted

Only enable the observe-resize when needed