HTMLMediaElement controlsList explained

Pull request to whatwg/html


Offers a way to control the native controls elements/buttons that are being shown by the user agent in order to be able to remove some features that do not make sense or are not part of the expected user experience or only allowlist a limited amount of features.


The current control web developers have over the HTMLMediaElement controls is via the controls attribute which is a boolean attribute. In other words, web developers can tell the user agent whether controls should be shown. Historically, specific use cases have been handled with “custom controls” which are implemented by having no native controls a set of elements added on top of the video.

With the media experience on the web getting richer, more controls are being added to the native user agent controls. These controls sometimes can look out of place or not work properly. For example, fullscreen and remote playback buttons might not always make sense. Similarly, browser adding download buttons have to implement heuristics that might sometimes fail, thus add a button that will not download usable content. Switching to custom controls can be a hard change for websites and their users, requiring user experience analysis, cross-browser implementation and accessibility considerations. Furthermore, native controls help user agents to build a tailored experience to their users based on their environment, their device and their habits in a way that custom controls can’t always achieve.


The proposed design is to have a allowlist/blocklist ability on native controls with the ability to set them directly from HTML content. A new content attribute controlslist is to be added as a space separated list of keywords being reflected as controlsList, having an effect only if the controls attribute is set.


The main use case is to able to remove some features/elements from the native controls. Blocklisting elements could be done with keywords starting with no such as nofullscreen or nodownload. For example, controlslist="nofullscreen nodownload". It would tell the user agent to show the usual native control without a fullscreen nor a download button.


A less common use case that could be resolved within the scope of this API change would be to allow a website to specify the exhaustive list of controls to show. In order to do so, the list of keywords will have to only contain allowlisted elements (without a no prefix). For example, controlslist="play timeline volume" would allow a website to request the user agent to show native controls with only a play button, a timeline, and a volume control.

The allowlisting proposal is here for completeness. The feature can be implemented and specified incrementally, allowing only for blocklisting of some elements to be supported first.

Edge cases

Blocklisting could be done such as no button would be visible. The specification should disallow this by either enforcing the play/pause button to always be available or by adding a play/pause button if all the elements have been removed.

Blocklist and allowlists can technically be put together (ie. controlslist="play nodownload"). In the spirit of blocklisting being the main feature of this proposal, blocklisting should always be used if one element is blocklisted, thus ignoring all allowlist keywords.

Backward compatibility

The backward compatibility will be preserved given that a user agent that does not support the controlsList feature will just ignore controlslist="foo bar".

Keywords and feature detection

The available keywords should be defined per spec. The controlsList will reflect the controls attribute as a DOMTokenList for which the supported tokens will be the keywords (eg. nodownload). The available keywords should be defined in the specification but some user agents might not support some of them. For example, a remote feature might not be implemented by all user agents. Looking at the controlsList tokens will allow authors to do feature detection.


The feature is meant to be implemented and designed incrementally. The ability to blocklist buttons is the main focus of this proposal and should be able to work independently of the allowlist approach. In addition, all buttons are not supposed to be supported initially. The spirit being that keywords should be added to the specification with user agents implementing support for blocklisting of new parts of the native controls.

IDL and attribute reflection

partial interface HTMLMediaElement {
  [SameObject, PutForwards=value] readonly attribute DOMTokenList controlsList;

The controlsList property will reflect the controlslist attribute as a DOMTokenList with a list of supported tokens.


Usage in HTML:

<video controls controlslist="nofullscreen nodownload noremoteplayback noplaybackrate foobar"></video>

Usage in Javascript:

var video = document.querySelector('video');
video.controls; // true
video.controlsList; // "nofullscreen nodownload noremoteplayback noplaybackrate" - "foobar" not present
video.controlsList; // "nofullscreen nodownload noplaybackrate" - "noremoteplayback" not present
video.getAttribute('controlslist'); // "nofullscreen nodownload noplaybackrate"