Media
The Media component displays media content from your Fluid playlist with various display modes.
Usage
<!-- Display a specific Playlist --> <fluid-media-widget playlist-id="your-playlist-id"></fluid-media-widget> <!-- Display specific media --> <fluid-media-widget media-id="your-media-id"></fluid-media-widget>
Attributes
| Attribute | Type | Default | Description |
|---|---|---|---|
playlist-id | string | — | Playlist ID to fetch media from |
media-id | string | — | Single media ID to display |
hide-widget | boolean | false | Whether to hide the component |
hide-secondary-widgets | boolean | false | Whether to hide secondary widgets (cart, chat, banner, popup) |
class-name | string | — | Additional CSS classes |
height | string | — | Thumbnail height |
width | string | — | Thumbnail width |
Display Options
| Attribute | Type | Default | Description |
|---|---|---|---|
embed-type | string | 'default' | Display mode: 'popover', 'inline', 'inline-shopping', 'default' |
auto-open | boolean | false | Auto-open on load (popover mode only) |
thumbnail-foam | boolean | false | Use object-cover for thumbnail |
Video Playback Options
These options only apply to video media types and are ignored for images, PDFs, and website embeds.
| Attribute | Type | Default | Description |
|---|---|---|---|
autoplay | boolean | false | Auto-play video when loaded |
autoplay-audio | boolean | false | Play audio on autoplay (only applies when autoplay is true) |
loop | boolean | false | Loop video playback when it ends |
cover-image | string | — | Cover image URL shown before first play (overrides API thumbnail) |
start-position | number | 0 | Start playback at this position (in seconds) |
Display Modes
Default Mode
Shows media with associated cta options (this is what is displayed on the shareable media pages)
<fluid-media-widget media-id="your-media-id" embed-type="default" ></fluid-media-widget>
Popover Mode
Shows a thumbnail that opens media in a popover overlay: auto-open true enabled will open the popover on load
<fluid-media-widget media-id="your-media-id" embed-type="popover" auto-open="true" ></fluid-media-widget>
Inline Mode
Embeds media directly in the page:
<fluid-media-widget media-id="your-media-id" embed-type="inline" ></fluid-media-widget>
Examples
Custom Dimensions
<fluid-media-widget playlist-id="your-playlist-id" height="300px" width="500px" ></fluid-media-widget>
Auto-Opening Popover
<fluid-media-widget media-id="your-media-id" embed-type="popover" auto-open="true" ></fluid-media-widget>
Autoplay Muted
<fluid-media-widget media-id="your-media-id" autoplay="true" ></fluid-media-widget>
Autoplay with Sound
<fluid-media-widget media-id="your-media-id" autoplay="true" autoplay-audio="true" ></fluid-media-widget>
Looping Video with Start Position
<fluid-media-widget media-id="your-media-id" loop="true" start-position="5" ></fluid-media-widget>
Custom Cover Image
<fluid-media-widget media-id="your-media-id" cover-image="https://example.com/custom-thumbnail.jpg" ></fluid-media-widget>
All Video Options Combined
<fluid-media-widget media-id="your-media-id" autoplay="false" loop="true" cover-image="https://example.com/cover.jpg" start-position="10" ></fluid-media-widget>
Hide Secondary Widgets
When embedding media on a page where you only want the video player without supplementary FairShare widgets (cart, chat, banner, popup):
<fluid-media-widget media-id="your-media-id" hide-secondary-widgets="true" ></fluid-media-widget>
Video Playback Behavior
Autoplay Behavior
When autoplay="true":
- If
autoplay-audio="false"(default): Video auto-plays muted - If
autoplay-audio="true": Video auto-plays with sound (may be blocked by browser policies)
Note: Most browsers block autoplay with sound unless the user has interacted with the page. Always default to muted autoplay for best compatibility.
Cover Image Behavior
When autoplay="false" (default) and a cover image is available (via cover-image attribute or API thumbnail):
- A cover image overlay with a centered play button is displayed over the video
- Clicking anywhere on the cover starts video playback
- The cover image disappears permanently after first play
- Even if the user pauses the video, the cover will not reappear
When autoplay="true":
- No cover overlay is shown (video plays immediately)
- The native HTML5 poster attribute is used as a fallback
This "one-time cover" pattern provides a clean user experience where the cover acts as an invitation to play, rather than repeatedly appearing on pause.
CTA Options
Customize the Call-to-Action (CTA) displayed with media. See Media CTA Options for full documentation.
| Type | Description |
|---|---|
cart | Add to cart (displays tagged products) |
link | External URL link |
email | Email/contact form |
phone | Phone contact |
Quick Example:
<!-- Set CTA via HTML attribute --> <fluid-media-widget media-id="12345" cta-options-manual-override='{"type":"cart"}' ></fluid-media-widget>
// Set CTA via SDK API FairShareSDK.media.settings.setForMedia("12345", { ctaOptionsManualOverride: { type: "cart" } });
JavaScript API
// Get media data const media = await window.FairShareSDK.getMedia("media-slug-or-id");
SDK Playback Settings API
Playback settings can be configured programmatically via the SDK. These serve as defaults that can be overridden by embed code attributes.
Set Default Playback Settings
// Set default playback settings for all media widgets FairShareSDK.media.settings.setDefault({ hideSecondaryWidgets: true, playbackSettings: { autoplay: true, autoplayAudio: false, loop: false, startPosition: 0, coverImage: "https://example.com/default-cover.jpg", }, });
Set Settings for Specific Media
// Set playback settings for a specific video FairShareSDK.media.settings.setForMedia("video-123", { hideSecondaryWidgets: true, playbackSettings: { loop: true, startPosition: 10, coverImage: "https://example.com/video-specific-cover.jpg", }, });
Set Settings for a Playlist
// Set playback settings for all videos in a playlist FairShareSDK.media.settings.setForPlaylist("playlist-456", { hideSecondaryWidgets: true, playbackSettings: { autoplay: true, coverImage: "https://example.com/playlist-cover.jpg", }, });
Configuration Priority
Playback settings can be configured at multiple levels (highest priority first):
- Component attributes (embed code) — Always wins
- SDK per-media settings (
FairShareSDK.media.settings.setForMedia()) - SDK per-playlist settings (
FairShareSDK.media.settings.setForPlaylist()) - SDK default settings (
FairShareSDK.media.settings.setDefault())
Event Tracking
You can track user interactions with media widgets using event listeners. See Media Event Listeners for full documentation.
Quick Example:
// Track when users start watching FairShareSDK.media.onStart((payload) => { console.log('Media started:', payload.mediaId); }); // Track CTA clicks FairShareSDK.media.onCtaActionClick((payload) => { if (payload.ctaType === 'cart') { console.log('Product added:', payload.productId); } });
Related
- Media CTA Options — Customize Call-to-Action buttons
- Media Event Listeners — Track media playback and CTA events
- getMedia — Get media data programmatically
- Playlist — Display a playlist of media