Appearance
Media — wd-media
Category: Promo · Tag:
wd-mediaBack to: Components overview
What it does
Puts a video on the page, full width at a height you choose. It works in two ways:
- Inline — the video plays right where it sits. With Autoplay it starts on its own and loops (a background video behind a heading, for example).
- Modal — the block becomes a card: a cover image, a dark overlay, your own content (a heading, a line of text) and a round play button. Clicking it opens the video in a modal over the page.
The video can come from the File Manager, any direct video URL, or a YouTube or Vimeo link.
Adding it & its settings
Add Component → Promo → Media.
Basic Settings (all components): #id, Classes, Inline Style.
Component Settings:
| Setting | What it does |
|---|---|
| Video source (required) | A File Manager video (/web-assets/<file name>), a direct video URL (.mp4, .webm), a YouTube link (youtube.com/watch?v=…, youtu.be/…, /shorts/…), a Vimeo link, or $$field to bind a dynamic-content field. |
| Cover image | Shown on the modal card, and on an inline file video before it plays. Empty = the YouTube thumbnail for YouTube links, otherwise the video's first frame. Also accepts $$field. |
| Title | The accessible name of the play button and the player ("Play: How we make our burgers"). Recommended. |
| Height (vh) | The block's / card's height as a share of the screen height (10–100, default 60). The width is always 100% of its container. |
| Open in a modal | On = the card + play button + modal. Off = the inline video. |
| Autoplay | Inline only (disabled when Open in a modal is on). Starts on its own and loops; the native controls are hidden. |
| Enable sound | Play with sound. See Sound and autoplay below. |
Content inside the element
Anything you place inside the element (headings, text, buttons) is shown over the video: centred on the inline block, or above the play button on the card. Leave it empty for a plain video.
Dynamic sources ($$field)
On a dynamic page, set the source (or the cover image) to $$ + the field name (e.g. $$promo_video) and each item shows its own video. If the field is missing or empty, the component renders nothing at all — that's intentional.
Sound and autoplay
Browsers only allow a page to play sound after the visitor has interacted with it. So:
| Mode | Autoplay | Enable sound | What happens |
|---|---|---|---|
| Inline | off | off / on | Native controls; plays muted / with sound when the visitor presses play. |
| Inline | on | off | Starts muted and loops. |
| Inline | on | on | Tries with sound. If the browser refuses (the usual case on a first visit), it plays muted and shows an unmute button in the corner. |
| Modal | — | off / on | Opening the modal is a click, so the video starts straight away — with sound when Enable sound is on. |
YouTube and Vimeo players can't report a refused autoplay, so an inline autoplaying embed always starts muted — their own player shows the unmute control.
The modal
- Opens from the play button (or from page code:
document.querySelector('#id').toggleMedia()). - It's a native dialog in the browser's top layer: it always appears above sticky headers and z-indexed sections — no z-index tuning needed.
- Close with the ✕ button, a click on the backdrop, or Esc. Closing stops the video (the player is removed).
- The page behind can't scroll while it's open.
- Emits
mediaToggled(detail.state:1opened,0closed).
Styling
CSS variables
Block and card
| Variable | Default |
|---|---|
--wd-media-border-radius | 0 |
--wd-media-background | #000 |
--wd-media-object-fit | cover (inline video) |
--wd-media-poster-position | center |
--wd-media-overlay | rgba(0, 0, 0, 0.45) (card overlay) |
--wd-media-content-color | #fff |
--wd-media-content-text-align | center |
--wd-media-content-justify | center (inline content's vertical position) |
--wd-media-content-padding | 2rem |
--wd-media-content-gap | 1.5rem (content ↔ play button) |
Buttons
| Variable | Default |
|---|---|
--wd-media-play-size | 5rem |
--wd-media-play-background | #fff |
--wd-media-play-color | #111 |
--wd-media-play-box-shadow | 0 10px 30px rgba(0,0,0,0.3) |
--wd-media-unmute-background | rgba(0, 0, 0, 0.6) |
--wd-media-unmute-color | #fff |
Modal
| Variable | Default |
|---|---|
--wd-media-modal-width | min(90vw, (90vh − bar) × 16/9) (the 16:9 player and the close bar fit in 90vh) |
--wd-media-bar-height | 3rem (the bar above the player that holds ✕ — kept off the player so it never covers the embed's own controls) |
--wd-media-modal-border-radius | 0.5rem |
--wd-media-shader-background | rgba(0, 0, 0, 0.8) (the backdrop) |
--wd-media-shader-blur | 0px |
css
/* example: an orange play button and rounded corners */
wd-media {
--wd-media-border-radius: 1.5rem;
--wd-media-play-background: #f05523;
--wd-media-play-color: #fff;
}::part()
| Part | Element |
|---|---|
media-<id> | The block (inline) or the card (modal). |
Notes
- A missing source renders nothing — check the URL or the dynamic field name first.
- Prefer short, compressed files for inline autoplay (a few MB); a large video slows the page for every visitor. Long videos are better on YouTube or Vimeo.
- Respects reduced motion: the play button's hover and the modal's open animation are switched off.