| description | Add YouTube, Vimeo, or MP4 video to a page |
|---|
The Video component displays one YouTube, Vimeo, or MP4 video. It supports autoplay rules, start time, looping, player controls, a custom thumbnail, responsive framing, and an optional lightbox.
{% embed url="https://youtu.be/avzBCXIJFU0" %}
- YouTube
- Vimeo
- MP4
Add a YouTube or Vimeo URL to Resources by dragging it from your browser. Add a local MP4 from Finder or import a remote URL.
{% hint style="success" %} To use a video as a section background, choose Video in a Container background. Watch the background video tutorial. {% endhint %}
You’ll find Video under Media in the Components list.
- Add the video to Resources.
- Drag Video onto the page.
- Select the video under Video → Resource.
- Choose autoplay, sound, controls, looping, and start time.
- Configure the thumbnail, aspect ratio, and optional lightbox.
- Preview playback in a browser.
The Video component also has a drop zone for a custom play button, text, or graphic.
Autoplay
- Immediately — Attempts to play when the page loads.
- When in Viewport — Plays when the video enters the viewport.
- Never — Waits for the visitor. This is the default.
Muted is enabled by default. Most browsers require muted audio for autoplay.
Controls shows or hides native player controls. Loop restarts the video when it finishes. These controls apply where supported by the selected video type.
Time (seconds) sets the playback start point and defaults to 0.
The Video group controls the source and playback behaviour.
Enable opens the video in an overlay and is off by default.
When enabled, Color defaults to Black, Opacity to 50%, and Blur to 0 pixels.
Lightbox backdrop controls.
Type can be Resource, Custom, or CMS. Resource is the default.
Mode switches between Light and Dark thumbnail sources. Custom uses a URL or path; CMS uses a field expression defaulting to {{item.image.src}}.
As with the Image component, the CMS field must be a Twig expression that outputs the image's URL, like the default {{item.image.src}} — a front matter key on its own won't work.
Custom and CMS thumbnails provide Alt text.
Overlay Color defaults to Surface 50 and Opacity to 50%.
{% hint style="info" %} YouTube resources automatically provide a default thumbnail. Add your own when you need consistent branding or a different crop. {% endhint %}
Thumbnail settings control the image shown before playback.
Aspect Ratio offers Auto, Wide 16:9, Tall 4:5, or Custom. Auto is the default; Custom defaults to 7/5.
For a fixed ratio, Object Fit offers Fill, Contain, Cover, None, or Scale Down and defaults to Cover. Position sets the thumbnail focal point and defaults to Centre.
The aspect ratio controls the thumbnail frame rather than changing the source video’s dimensions.
Aspect Ratio controls the thumbnail frame and crop.
A custom thumbnail ratio can use any valid x/y value.
Provide captions or a transcript for spoken content. Avoid unexpected audio, retain usable player controls, and describe custom thumbnails when they convey information.
- Mute autoplay: It is required by most browsers and avoids surprising visitors.
- Use an intentional thumbnail: A compressed JPG usually offers good quality and performance.
- Avoid autoplay for essential content: Give visitors direct control over important videos.
- Image — Shares thumbnail source and aspect-ratio controls.
- Gallery — Combines several videos and images in one lightbox.
- Container — Supports background video.
{% include "../../.gitbook/includes/common-controls.md" %}