Signatur
Beschreibung
Die Eigenschaft controls ist ein boolescher Wert, der direkt das gleichnamige HTML-Attribut von <video>- und <audio>-Elementen widerspiegelt. Ist sie true, blendet der Browser seine eingebaute Bedienleiste ein, meist mit Wiedergabe/Pause, Zeitleiste, Lautstärke, Vollbild und gegebenenfalls Untertiteln.
Setzen Sie element.controls = true, fügt der Browser das Attribut controls hinzu. Mit false wird es entfernt. Die Eigenschaft und das Attribut sind also immer synchron. Beim Lesen erhalten Sie nur true oder false, nie den Textwert des Attributs.
Typische Anwendungsfälle:
- Eigene Bedienoberfläche bauen: Die nativen Steuerelemente werden ausgeblendet, sobald JavaScript geladen ist. Ohne JavaScript bleiben sie als Rückfallebene erhalten (progressive Verbesserung).
- Steuerelemente erst nach einer Interaktion oder nach einem Intro-Clip einblenden.
- Hintergrundvideos ohne Bedienleiste abspielen.
Aussehen und Umfang der nativen Steuerelemente legt allein der Browser fest. Mit CSS lassen sie sich kaum einheitlich gestalten. Einzelne Schaltflächen können Sie über controlsList ausblenden, allerdings nur in Chromium-Browsern.
Rückgabewert
true, wenn das Attribut controls gesetzt ist und der Browser Steuerelemente anzeigt, sonst false. Die Eigenschaft ist les- und schreibbar.Beispiele
Steuerelemente abfragen und umschalten
const video = document.querySelector('video');
console.log(video.controls); // z. B. false
// Steuerelemente einblenden
video.controls = true;
console.log(video.hasAttribute('controls'));
// Wieder ausblenden
video.controls = !video.controls;
console.log(video.controls);Progressive Verbesserung: native Steuerelemente durch eigene ersetzen
// HTML: <video id="player" src="film.mp4" controls></video>
// <button id="play" hidden>Wiedergabe</button>
const player = document.getElementById('player');
const playBtn = document.getElementById('play');
// Nur mit aktivem JavaScript eigene Bedienung verwenden
player.controls = false;
playBtn.hidden = false;
playBtn.addEventListener('click', async () => {
if (player.paused) {
await player.play();
playBtn.textContent = 'Pause';
} else {
player.pause();
playBtn.textContent = 'Wiedergabe';
}
});Audio-Element dynamisch mit Steuerelementen erzeugen
const audio = new Audio('podcast.mp3');
console.log(audio.controls); // Standard: false, das Element ist unsichtbar
audio.controls = true;
audio.preload = 'metadata';
document.body.append(audio);
console.log(audio.outerHTML);Steuerelemente erst nach Ende des Intros einblenden
const video = document.querySelector('#intro-video');
video.controls = false;
video.muted = true;
video.addEventListener('ended', () => {
video.controls = true; // der Nutzer kann nun selbst steuern
}, { once: true });
video.play().catch((err) => console.warn('Autoplay blockiert:', err.name));// Wichtig · Fallstricke
- Attributwert spielt keine Rolle:
controls="false"im HTML aktiviert die Steuerelemente trotzdem, weil nur das Vorhandensein des Attributs zählt. Zum Deaktivieren entfernen Sie das Attribut oder setzenelement.controls = false. - Unsichtbares Audio: Ein
<audio>-Element ohnecontrolswird nicht dargestellt. Es lässt sich dann nur per Skript steuern. - Barrierefreiheit: Die nativen Steuerelemente sind mit Tastatur und Screenreader bedienbar. Wer sie durch eigene ersetzt, muss Fokus, ARIA-Beschriftungen und Tastaturbedienung selbst umsetzen.
- Mobile Browser: iOS Safari spielt Videos ohne
playsinlineteilweise im Vollbild mit eigenen Steuerelementen ab. Das geschieht unabhängig voncontrols. - Autoplay:
controls = falsebeeinflusst die Autoplay-Regeln nicht. Automatische Wiedergabe funktioniert weiterhin meist nur stummgeschaltet (muted). - Kompatibilität: Wird von allen modernen Browsern unterstützt.
controlsList(z. B.nodownload) gibt es dagegen nur in Chromium-Browsern.