CardVideo

Embedded video card with YouTube/Vimeo provider URLs or direct-file playback, thumbnail-first modes, and optional title and caption text below the media.

Best for

product videoscampaign trailerstutorial playback

Import

import { CardVideo } from "@enadhq/enad-react-sdk/client/storefront"

When to use it

Use CardVideo when a page needs playable video inside the SDK surface instead of sending the shopper away to another tab.

CardVideo supports two source classes in v1:

a supported provider page/share URL through providerUrl
a direct hosted video file through videoSrc

Keep the component bounded to YouTube, Vimeo, and direct file playback. It does not accept raw iframe HTML, provider SDK snippets, or Storyblok-specific fields.

Composition notes

CardVideo is still a small, prop-driven component, but it now has clear playback behavior:

thumbnail is the preview image used by thumbnail-inline and thumbnail-lightbox.
providerUrl normalizes a supported YouTube or Vimeo URL into a safe embed URL.
videoSrc renders a native HTML <video> player.
playbackMode controls when and where the player mounts:
- immediate
- thumbnail-inline
- thumbnail-lightbox
autoplay, muted, and playsInline forward to the mounted player when the source supports them. Thumbnail-gated modes never autoplay before user interaction.
title and caption render below the media and also help label the trigger or player.
videoUrl remains available as a compatibility alias for older code, but new code should prefer providerUrl or videoSrc.

Behavior and theming guidance

Use immediate when the page should show the player right away. Use thumbnail-inline when the page should keep its place and reveal the player only after intent. Use thumbnail-lightbox when the page needs a thumbnail preview state and more room for playback in a dialog.

Native file playback uses browser media controls. Provider playback stays bounded to supported embed URLs only.

For autoplay examples, pair autoplay with muted so the result stays browser-friendly. If the page needs a thumbnail-first experience, keep autoplay off until the shopper actively opens the player.

Examples

Live examples you can edit directly in the sandbox.

1 example

Thumbnail lightbox provider example

A YouTube or Vimeo URL can stay thumbnail-first, then open inside the shared SDK dialog shell when the shopper chooses to play it.

Component Sets

Preview the first example across the available component-set presets to compare tone, spacing, and structural defaults.

Props

Prop	Type	Default	Description
thumbnail	string	—	Optional preview image used by the thumbnail-gated playback modes
providerUrl	string	—	Provider page or share URL for a supported video host. `CardVideo` currently normalizes YouTube and Vimeo only. `videoSrc` wins when both source props are provided.
videoSrc	string	—	Direct hosted video-file URL rendered through a native HTML video element. When both `videoSrc` and `providerUrl` are supplied, `videoSrc` wins.
videoUrl	string	—	Legacy compatibility alias. Prefer `providerUrl` for supported provider embeds or `videoSrc` for direct files in new code. This alias is only considered when neither new source prop is provided.
title	string	—	Optional title rendered below the media and reused for trigger/player labelling
caption	string	—	Optional supporting copy rendered below the title
aspectRatio	string	16:9	Aspect ratio of the preview and player shell
playbackMode	string	immediate	Controls whether playback starts immediately, mounts inline after thumbnail activation, or opens inside a lightbox dialog
autoplay	boolean	false	Requests autoplay on the mounted player. Thumbnail-gated modes never autoplay before user interaction.
muted	boolean	false	Forwards the muted flag to the mounted player or provider embed params when supported
playsInline	boolean	false	Forwards the playsInline hint to the mounted player or provider embed params when supported
className	string	—	No description yet.