Runnable HTML Docs: Video Tag

Q: How do I add a video in HTML?

Use . The controls attribute shows the browser's play button, timeline and volume. Without it, the video shows its first frame (or poster) and cannot be started by the user.

Q: Why is autoplay not working on my video?

Browsers block autoplay with sound. Add muted next to autoplay, and playsinline so iPhones play it in the page instead of fullscreen: .

Q: How do I add a thumbnail to a video?

Use the poster attribute with an image URL: . The image shows until the video starts playing.

Q: How do I add subtitles to an HTML video?

Add a inside the video. The file uses the WebVTT format, and the browser shows a captions button in its controls.

Q: How do I make a video responsive?

Set width: 100% and height: auto in CSS (or max-width: 100%). The video scales with its container and keeps its aspect ratio.

How to add a video

Point the <video> element at a video file and add controls so the reader can play it:

<video src="movie.mp4" controls width="640"></video>

controls shows the browser's own player: play and pause, a timeline, volume and fullscreen. Without it the video just sits there. This preview cannot load video files, so the examples on this page feed the element from a small canvas animation drawn by a script; the attributes work exactly as they do with a file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Video</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <video id="player" controls muted width="320" height="180"></video>
  <p>Press play.</p>
  <script>
    // Stand-in for a video file: an animation drawn on a canvas
    const canvas = document.createElement('canvas');
    canvas.width = 320; canvas.height = 180;
    const ctx = canvas.getContext('2d');
    let x = 0;
    (function draw() {
      ctx.fillStyle = '#111827'; ctx.fillRect(0, 0, 320, 180);
      ctx.fillStyle = '#f59e0b'; ctx.beginPath();
      ctx.arc(30 + (x % 260), 90, 24, 0, Math.PI * 2); ctx.fill();
      x += 2; requestAnimationFrame(draw);
    })();
    document.getElementById('player').srcObject = canvas.captureStream(30);
  </script>
</body>
</html>

Because the source is a live stream rather than a file, the timeline cannot be dragged here and there is no fixed length. With a real .mp4, the same player gets a full seek bar.

Video attributes

Attribute	What it does
`controls`	Shows the browser's player controls
`autoplay`	Starts playing as soon as it can (only when `muted`, in practice)
`muted`	Starts with the sound off
`loop`	Starts again from the beginning when it ends
`playsinline`	Plays in the page on iPhone instead of switching to fullscreen
`poster="thumb.jpg"`	Image shown before the video plays
`preload`	`none`, `metadata` (just size and length) or `auto` (the browser decides how much to download)
`width`, `height`	Size in pixels; setting both reserves space before the video loads

Autoplay, muted and loop

Browsers block videos that start by themselves with sound. A muted video may autoplay, which is how background videos and short looping clips work:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Autoplay</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    .hero { position: relative; width: 320px; height: 180px; border-radius: 10px; overflow: hidden; }
    .hero video { width: 100%; height: 100%; object-fit: cover; }
    .hero h1 { position: absolute; inset: auto 0 0 0; margin: 0; padding: 10px; color: #fff; font-size: 20px; background: rgba(0, 0, 0, 0.45); }
  </style>
</head>
<body>
  <div class="hero">
    <video id="bg" autoplay muted loop playsinline></video>
    <h1>Background video</h1>
  </div>
  <p id="state"></p>
  <script>
    const canvas = document.createElement('canvas');
    canvas.width = 320; canvas.height = 180;
    const ctx = canvas.getContext('2d');
    let t = 0;
    (function draw() {
      ctx.fillStyle = 'hsl(' + (t % 360) + ', 70%, 45%)';
      ctx.fillRect(0, 0, 320, 180);
      t += 1; requestAnimationFrame(draw);
    })();
    const video = document.getElementById('bg');
    video.srcObject = canvas.captureStream(30);
    video.addEventListener('playing', () => {
      document.getElementById('state').textContent = 'Playing without a click, because it is muted.';
    });
  </script>
</body>
</html>

The four attributes work as a set: autoplay to start, muted so the browser allows it, loop for a clip, and playsinline so iPhones do not open it fullscreen. Autoplaying video with sound is not only blocked, it is also a problem for screen reader users, whose speech gets drowned out. If a clip plays longer than five seconds, give people a way to pause it.

Poster image and preload

poster shows an image before the video plays, like a thumbnail. Here the video has no source at all, so the poster is all there is to see:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Poster</title>
</head>
<body style="font-family: system-ui, sans-serif;">
  <video controls width="320" height="180" preload="none"
    poster="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='180'%3E%3Crect width='320' height='180' fill='%232563eb'/%3E%3Ctext x='160' y='98' font-family='Arial' font-size='22' fill='white' text-anchor='middle'%3EEpisode 1: Intro%3C/text%3E%3C/svg%3E">
  </video>
</body>
</html>

With preload="none" the browser downloads nothing until the reader presses play, and the poster keeps the space from looking empty. Use preload="metadata" when you want the duration visible before playing. Without a poster, most browsers show the first frame once they have loaded it.

Formats and fallbacks with source

Instead of src, you can list several files with <source> elements. The browser plays the first one it supports:

<video controls width="640" poster="thumb.jpg">
  <source src="movie.webm" type="video/webm">
  <source src="movie.mp4" type="video/mp4">
  <track kind="captions" src="captions.vtt" srclang="en" label="English">
  <p>Your browser cannot play this video. <a href="movie.mp4">Download it</a>.</p>
</video>

MP4 with H.264 video plays in every current browser, so it is the safe choice when you have only one file. The type attribute lets the browser skip formats it cannot play without downloading them. The text at the end shows only in browsers that do not support <video> at all.

Captions with track

<track kind="captions"> loads a WebVTT file, a plain text file of timed lines. The browser adds a captions button to its controls and draws the text over the video:

WEBVTT

00:00:00.000 --> 00:00:03.000
Welcome to the course.

00:00:03.000 --> 00:00:06.500
Today we build our first web page.

Captions help deaf and hard of hearing viewers, people watching with the sound off, and anyone following a video in a second language. Add default to a track to show it without a click. A caption file from another domain needs CORS headers and crossorigin on the video.

Style and control it with JavaScript

A video is a replaced element, like an image: width: 100% with height: auto makes it responsive, and object-fit decides how it fills a box of a different shape. JavaScript gets play(), pause(), currentTime, volume and events such as play, pause and ended:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Custom controls</title>
  <style>
    body { font-family: system-ui, sans-serif; margin: 12px; }
    video { width: 100%; max-width: 360px; height: auto; border-radius: 10px; display: block; }
    button { font: inherit; margin-top: 8px; padding: 6px 14px; }
  </style>
</head>
<body>
  <video id="v" muted width="320" height="180"></video>
  <button id="toggle">Play</button>
  <span id="status">Paused</span>
  <script>
    const canvas = document.createElement('canvas');
    canvas.width = 320; canvas.height = 180;
    const ctx = canvas.getContext('2d');
    let a = 0;
    (function draw() {
      ctx.fillStyle = '#e5e7eb'; ctx.fillRect(0, 0, 320, 180);
      ctx.fillStyle = '#16a34a'; ctx.beginPath();
      ctx.arc(160 + Math.cos(a) * 60, 90 + Math.sin(a) * 60, 16, 0, Math.PI * 2); ctx.fill();
      a += 0.05; requestAnimationFrame(draw);
    })();
    const video = document.getElementById('v');
    const button = document.getElementById('toggle');
    const status = document.getElementById('status');
    video.srcObject = canvas.captureStream(30);
    button.onclick = () => (video.paused ? video.play() : video.pause());
    video.addEventListener('play', () => { button.textContent = 'Pause'; status.textContent = 'Playing'; });
    video.addEventListener('pause', () => { button.textContent = 'Play'; status.textContent = 'Paused'; });
  </script>
</body>
</html>

play() returns a promise that rejects when the browser blocks playback (for example, unmuted autoplay), so production code should catch it. Building your own controls is optional; the built-in controls are keyboard accessible and translated, which custom buttons have to reproduce. For videos hosted on YouTube or Vimeo, you embed their player with an iframe instead.

Common mistakes

Autoplay without muted. The browser blocks it. Add muted and playsinline.
Forgetting controls. Unless you build your own, the reader has no way to start the video.
No width and height. The page jumps when the video loads. Set both, then scale with CSS.
Huge files. Compress videos for the web and use preload="none" or "metadata" for videos lower on the page.
No captions on videos with speech. Add a <track kind="captions">.

Frequently Asked Questions

How do I add a video in HTML?

Use <video src="movie.mp4" controls width="640"></video>. The controls attribute shows the browser's play button, timeline and volume. Without it, the video shows its first frame (or poster) and cannot be started by the user.

Why is autoplay not working on my video?

Browsers block autoplay with sound. Add muted next to autoplay, and playsinline so iPhones play it in the page instead of fullscreen: <video autoplay muted loop playsinline>.

What video format should I use for the web?

MP4 with H.264 video plays in every current browser, so it is the safe default. You can list a smaller WebM file first with <source> and let the browser pick the first format it supports.

How do I add a thumbnail to a video?

Use the poster attribute with an image URL: <video poster="thumb.jpg" controls>. The image shows until the video starts playing.

How do I add subtitles to an HTML video?

Add a <track kind="captions" src="captions.vtt" srclang="en" label="English"> inside the video. The file uses the WebVTT format, and the browser shows a captions button in its controls.

How do I make a video responsive?

Set width: 100% and height: auto in CSS (or max-width: 100%). The video scales with its container and keeps its aspect ratio.

Related concepts