The HTML controls attribute
The HTML controls attribute tells the browser to show its own playback controls on an <audio> or <video> element. It is a boolean attribute, so writing controls is enough. Without it, the browser is not asked to draw its controls, although it may still offer some in a context menu.
Overview
The controls attribute asks the browser to draw its own playback interface on a media element. It is a boolean attribute of <video> and <audio>, and the HTML Standard reads its presence as a sign that the author has not built a scripted controller and wants the browser's controls instead.
The standard also lists what those controls should cover. That means play and pause, seeking, volume, captions and sign-language tracks, audio track choices, and a way to watch in fullscreen or a separate resizable window. Each browser draws its own version, so the exact buttons and their look differ between engines.
Leaving controls off has the biggest effect on <audio>. The rendering rules tell browsers to force an audio element that exposes no interface to display: none, whatever your CSS says, so it takes no space and the listener has nothing to click.
On video, the poster image or the first frame still shows without the attribute, but play, pause and seek then have to come from your own buttons. Browsers may still offer a few controls through a context menu or media keys, and the standard says they should show the full interface when scripting is disabled.
Syntax
<video src="tour.mp4" controls width="640" height="360"></video>
<audio src="podcast.mp3" controls></audio>Values
| Value |
|---|
| A boolean attribute: present or absent. |
Example
<video src="https://codeshack.io/web/example.mp4" controls width="150"></video>
<video src="https://codeshack.io/web/example.mp4" width="150"></video>
<p>The first video has controls. The second has none, so the page offers no button to start it.</p>Best practices
- Add
controlsto every <audio> element unless you build your own player, because an audio element without an interface is not rendered at all. - Keep
controlson video that uses autoplay, so viewers can pause the motion and switch the sound on or off. - If you replace the native interface, use real <button> elements with clear names for play, pause and mute, and make sure they all work from the keyboard.
- Test the native controls in every browser you support, since each engine draws its own buttons and menus.
- Treat
controlslistas an optional extra, because MDN's compatibility data lists it as unsupported in Firefox and Safari.
Accessibility
The controls attribute gives users the pause and volume mechanisms that WCAG expects. Success criterion 1.4.2 needs a way to pause or turn down audio that plays automatically for more than 3 seconds, and 2.2.2 needs a way to pause moving content that starts on its own, lasts longer than five seconds and sits alongside other content.
A custom player has to rebuild the same functions itself. Criterion 2.1.1 requires all functionality to be operable through a keyboard, and criterion 4.1.2 requires each control's name and role to be programmatically determinable, so custom play, seek and volume controls need keyboard support and accessible names.
