Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / HTML

controlslist — selecting native media controls

The controlslist attribute tells the browser which options to omit from native audio and video controls. Its JavaScript counterpart, HTMLMediaElement.controlsList, exposes a token list. Support depends on the browser.

Version: WICG Controls List draft; index snapshot date recorded separately

Syntax

controlslist="nodownload nofullscreen noremoteplayback"; media.controlsList.add("nodownload")

controlslist is an attribute on audio and video elements containing space-separated tokens. It helps the browser select its own media controls. It does not enable those controls by itself: the separate controls attribute does that. It also does not control player buttons implemented by the page author.

The nodownload token requests omission of the download option, nofullscreen of the fullscreen option, and noremoteplayback of the option for playback on a remote device. These tokens can be combined. They are interface hints, not content protection: hiding the download option does not protect the file from being saved.

HTMLMediaElement.controlsList is the attribute's JavaScript counterpart and returns a DOMTokenList. The attribute name is controlslist, whereas the property name is controlsList. The add(), remove(), and contains() methods let you manage tokens; changing the list updates the attribute. The retrieved property exposes an object whose contents can be modified.

Support is limited, so check for controlsList before using the API and test the interface in your target browsers. Detecting the property alone does not prove that every hint changes the controls' appearance. The example below checks synchronization between the list and attribute without loading media.

Examples

(() => {
  const video = document.createElement("video");
  video.controls = true;
  video.setAttribute("controlslist", "nodownload");

  if (!("controlsList" in video)) {
    console.log("controlsList: unsupported");
    return;
  }

  video.controlsList.add("nofullscreen");
  console.log(video.getAttribute("controlslist"));
  console.log(video.controlsList.contains("nodownload"));
})();

Result

nodownload nofullscreen
true

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources