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

Default

Responsive video with native controls.

<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>

.rounded

Applies rounded corners to the video player.

<video class="rounded" controls>...</video>

.full

Forces full container width.

Aspect Ratios

Force consistent aspect ratios for video content.

.widescreen (16:9) .standard (4:3) .square (1:1) .ultrawide (21:9)
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

Video 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

Background Video

Decorative looping video without controls.

<video autoplay muted loop playsinline> <source src="background.mp4" type="video/mp4" /> </video>

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 poster to show a meaningful preview image
  • Don't autoplay videos with sound - use muted for autoplay
  • Provide a text transcript for important video content
  • Ensure controls are keyboard accessible (native controls are)
  • Consider users who disable autoplay or animations

Respecting Motion Preferences

<!-- 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>

Related Elements

  • <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

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;