video
The video element embeds video content with native playback controls, responsive sizing, and aspect ratio variants for different video formats.
Description
The <video> element embeds video content with native browser playback controls. Vanilla Breeze styles videos to be responsive by default with a dark background, and provides aspect ratio variants for common video formats.
Videos support multiple <source> elements for format fallbacks and <track> elements for captions and subtitles.
When to Use
- Self-hosted video - Videos hosted on your own server
- Background video - Decorative looping video without controls
- Video galleries - Collections of video content
- Instructional content - Tutorials and how-to videos
When to Use iframe Instead
- YouTube, Vimeo, or other video hosting services - use
<iframe>embeds - Videos requiring DRM or advanced features provided by third-party players
Variants and Aspect Ratios
Vanilla Breeze provides variant classes for video styling (.rounded, .full) and aspect ratio classes (.widescreen, .standard, .square, .ultrawide) for consistent video dimensions.
Variant Classes
<video controls poster="poster.jpg"> <source src="video.mp4" type="video/mp4" /> <source src="video.webm" type="video/webm" /> Your browser does not support the video element.</video><video class="rounded" controls>...</video>Aspect Ratio Classes
| Class | Aspect Ratio | Use Case |
|---|---|---|
.widescreen |
16:9 | Standard HD video, YouTube, most modern content |
.standard |
4:3 | Classic TV, older content, some presentations |
.square |
1:1 | Social media (Instagram), thumbnails |
.ultrawide |
21:9 | Cinematic content, ultrawide monitors |
Background Video
Decorative looping video without controls. Combine autoplay, muted, loop, and playsinline for seamless background playback.
<video autoplay muted loop playsinline> <source src="background.mp4" type="video/mp4" /></video>Chapter Markers
Add data-chapter-list to a <track kind="chapters"> element to render a clickable chapter list below the video. The current chapter highlights during playback, and clicking a chapter seeks to that timestamp.
Without JavaScript, the video plays normally with chapters available in the browser's native UI where supported.
<video controls> <source src="tutorial.mp4" type="video/mp4" /> <track kind="chapters" src="chapters.vtt" default data-chapter-list /></video>WebVTT Chapter Format
Chapters use standard WebVTT format. Each cue defines a time range and chapter title:
WEBVTT 00:00:00.000 --> 00:02:30.000Introduction 00:02:30.000 --> 00:08:00.000Getting Started 00:08:00.000 --> 00:15:00.000Core Concepts 00:15:00.000 --> 00:22:00.000Building Your First Project 00:22:00.000 --> 00:28:00.000Summary and Next StepsVideo Attributes
| Attribute | Description |
|---|---|
controls |
Show native playback controls (play, pause, volume, fullscreen) |
poster |
Image shown before video loads or plays |
autoplay |
Start playing automatically (requires muted in most browsers) |
muted |
Start with audio muted |
loop |
Restart video when it ends |
playsinline |
Play inline on mobile instead of fullscreen |
preload |
none, metadata, or auto |
Motion Preferences
Vanilla Breeze respects prefers-reduced-motion for autoplay videos. When a user has indicated they prefer reduced motion, autoplay videos are paused automatically. This ensures background and decorative videos don't cause discomfort for motion-sensitive users.
<!-- CSS: Pause autoplay for motion-sensitive users -->@media (prefers-reduced-motion: reduce) { video[autoplay] { animation-play-state: paused; }} <!-- JavaScript alternative --><script>if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) { document.querySelectorAll('video[autoplay]').forEach(v => v.pause());}</script>Fallback Content
Provide fallback text or links for browsers that don't support video or the specified formats.
<video controls> <source src="video.webm" type="video/webm" /> <source src="video.mp4" type="video/mp4" /> <p> Your browser doesn't support HTML video. <a href="video.mp4">Download the video</a> instead. </p></video>Accessibility
Captions and Subtitles
Use <track> elements to provide captions for deaf and hard-of-hearing users.
<video controls> <source src="video.mp4" type="video/mp4" /> <!-- Captions (spoken content + sound effects) --> <track kind="captions" src="captions-en.vtt" srclang="en" label="English captions" default /> <!-- Subtitles (spoken content only) --> <track kind="subtitles" src="subtitles-es.vtt" srclang="es" label="Spanish subtitles" /></video>Best Practices
- Always provide captions for videos with speech
- Use
posterto show a meaningful preview image - Don't autoplay videos with sound - use
mutedfor autoplay - Provide a text transcript for important video content
- Ensure controls are keyboard accessible (native controls are)
- Consider users who disable autoplay or animations
Related
<audio>- Audio-only content, similar API<source>- Define multiple video sources for format fallback<track>- Captions, subtitles, and other timed text<figure>- Wrap videos that need captions<iframe>- Embed third-party video players<video-player>- Enhanced video playback with overlay controls, captions, fullscreen, and playlist support<audio-player>- Enhanced audio playback with progress, seeking, and playlist support<audio-visualizer>- Real-time audio frequency visualization
CSS Reference
Styles defined in /src/native-elements/video/styles.css
| Selector | Properties |
|---|---|
video |
max-inline-size: 100%; block-size: auto; display: block; background: var(--color-gray-900); |
video.full |
inline-size: 100%; |
video.widescreen |
aspect-ratio: 16 / 9; object-fit: cover; |
video.standard |
aspect-ratio: 4 / 3; object-fit: cover; |
video.square |
aspect-ratio: 1; object-fit: cover; |
video.ultrawide |
aspect-ratio: 21 / 9; object-fit: cover; |
video.rounded |
border-radius: var(--radius-m); overflow: hidden; |
.chapter-list |
Chapter list nav container rendered by data-chapter-list enhancer |
.chapter-list li[data-active] |
Highlights the currently playing chapter |