Skip to content
Tutorials Center
My learning

Topics

HTML Reference ยท Images and Media

The <video> element

Reference for the HTML <video> element: every attribute (controls, autoplay, muted, loop, preload, poster, playsinline and more), fallback sources and captions.

The <video> element embeds a video in the page and plays it with the browser's own player. With controls, viewers get play/pause, a timeline, volume, fullscreen and a captions menu; without it, the video is shown but you start and stop it from JavaScript.

Give the file with src, or list several formats with <source> children so each browser can choose one. Add captions with <track>.

HTML
<video controls width="640" height="360" src="/media/tour.mp4"></video>

Try it

A video with a poster and two formats

The poster image shows until the viewer presses play. With preload="none", nothing else is downloaded before that.

A silent looping background clip

Browsers allow autoplay when the video is muted, which is why muted is there. The pause button matters: moving content that plays for more than five seconds needs a way to stop it.

Attributes

Attribute Values Description
src URL The video file. Leave it out when you use <source> children.
controls Boolean Show the browser's player controls.
autoplay Boolean Start playing as soon as possible. Browsers generally allow it only when the video is also muted (or the user has interacted with the site).
muted Boolean Start with the sound off. Sets the initial muted state; the viewer can still unmute.
loop Boolean Start again from the beginning when the end is reached.
preload none, metadata, auto How much to download before playback: nothing, only metadata (duration, dimensions, first frame), or as much as the browser wants. An empty value means auto. The default varies by browser. It is only a hint; autoplay overrides it.
poster URL An image to show before playback starts. Without it, browsers show the first frame (once it is loaded) or a blank box.
playsinline Boolean Play inside the page instead of switching to fullscreen. Mainly matters on iPhone, where inline autoplay requires it.
width Non-negative integer The display width in CSS pixels.
height Non-negative integer The display height in CSS pixels. With width, reserves space before the video loads. The video keeps its aspect ratio inside the box (letterboxing if needed).
crossorigin anonymous, use-credentials Fetch the video (and its tracks) with CORS. Needed for caption files from another origin and for drawing frames into a <canvas> and reading them back.
controlslist nodownload, nofullscreen, noplaybackrate, noremoteplayback Non-standard (Chromium browsers only). Hides individual items from the built-in controls. It does not prevent downloading.
disablepictureinpicture Boolean Asks the browser not to offer picture-in-picture for this video. Defined by the Picture-in-Picture specification, not by HTML; not supported in every browser.
disableremoteplayback Boolean Hides the option to cast the video to a remote device (AirPlay, Chromecast and similar). Defined by the Remote Playback API; support varies.

It also accepts the global attributes and the media event attributes such as onplay, onpause, onended, onloadedmetadata and ontimeupdate.

Usage notes

  • Captions are not optional. Any video with speech or meaningful sound needs captions for viewers who can't hear it. Add them with <track kind="captions">, and offer a transcript for longer content.
  • Formats. MP4 with H.264 video and AAC audio plays everywhere. WebM (VP9 or AV1) and MP4 with AV1 are usually smaller. Put the smaller format first and MP4 last as the universal fallback.
  • Fallback content inside <video> is shown only by browsers that don't support the element at all. A failed download shows an empty player instead, so check your file paths and MIME types.
  • Respect motion and data. Avoid autoplaying video with sound, give looping clips a pause control, and consider the prefers-reduced-motion media query. Use preload="none" or metadata for videos the user may never play.
  • Responsive sizing. Set width and height to the video's real size, then add max-width: 100%; height: auto in CSS so it shrinks on small screens without distortion.
  • Third-party players. Videos hosted on YouTube or Vimeo are embedded with an <iframe>, not <video>.
  • Scripting. The HTMLMediaElement API gives you play() (returns a promise), pause(), currentTime, duration, volume, playbackRate, requestFullscreen() and many events.

Technical summary

Content categories Flow content, phrasing content, embedded content, palpable content; with controls: interactive content
Permitted content With src: zero or more <track> elements, then transparent content with no media elements. Without src: zero or more <source> elements, then zero or more <track> elements, then transparent content with no media elements
Tag omission None; both the start and end tags are required
Permitted parents Any element that accepts embedded content
Implicit ARIA role No corresponding role
DOM interface HTMLVideoElement
Default display inline (a replaced element; 300 ร— 150 pixels until the size is known)

Browser support

Supported in every browser; the supported codecs and the look of the built-in controls differ between browsers.