Fullscreen API JavaScript

Le plein écran est une fonctionnalité attendue dans les lecteurs vidéo, les jeux en ligne, les présentations et les visionneuses d'images. Avant la Fullscreen API, il fallait des hacks CSS ou Flash pour y parvenir. Aujourd'hui, une seule méthode JavaScript suffit — et elle fonctionne sur n'importe quel élément du DOM, pas seulement les vidéos.

Comme pour les autres APIs sensibles, le plein écran ne peut être activé qu'à la suite d'un geste utilisateur. Un script ne peut pas forcer le plein écran au chargement d'une page — le navigateur l'interdit pour protéger l'utilisateur contre les interfaces trompeuses.

Passer un élément en plein écran

requestFullscreen() s'appelle sur l'élément à agrandir. Elle retourne une Promise — utile pour savoir si l'opération a réussi ou été refusée :

Exemple :   📋 Copier le code

// Passer un élément spécifique en plein écran
async function activerPleinEcran(element) {
  try {
    await element.requestFullscreen();
    console.log('Plein écran activé.');
  } catch (erreur) {
    console.error('Impossible d\'activer le plein écran :', erreur);
  }
}

// Plein écran sur un élément vidéo
const video = document.getElementById('maVideo');
document.getElementById('btnPleinEcran').addEventListener('click', () => {
  activerPleinEcran(video);
});

// Plein écran sur toute la page
document.getElementById('btnPageEntiere').addEventListener('click', () => {
  activerPleinEcran(document.documentElement);
});

Quitter le plein écran

exitFullscreen() s'appelle sur document (et non sur l'élément). L'utilisateur peut aussi quitter à tout moment avec la touche Échap :

Exemple :   📋 Copier le code

// Quitter le plein écran
async function quitterPleinEcran() {
  try {
    await document.exitFullscreen();
    console.log('Plein écran désactivé.');
  } catch (erreur) {
    console.error('Erreur lors de la sortie :', erreur);
  }
}

// Vérifier si on est actuellement en plein écran
if (document.fullscreenElement) {
  console.log('Élément en plein écran :', document.fullscreenElement);
} else {
  console.log('Pas de plein écran actif.');
}

Basculer entre plein écran et mode normal

Le pattern le plus courant est un bouton qui alterne entre les deux états. On vérifie document.fullscreenElement pour savoir dans quel état on se trouve :

Exemple :   📋 Copier le code

const element = document.getElementById('monContenu');
const bouton = document.getElementById('btnToggle');

async function basculerPleinEcran() {
  if (!document.fullscreenElement) {
    // Pas en plein écran — activer
    await element.requestFullscreen();
    bouton.textContent = '⛶ Quitter le plein écran';
  } else {
    // En plein écran — désactiver
    await document.exitFullscreen();
    bouton.textContent = '⛶ Plein écran';
  }
}

bouton.addEventListener('click', basculerPleinEcran);

Détecter les changements d'état avec fullscreenchange

L'événement fullscreenchange se déclenche à chaque fois que le mode plein écran est activé ou désactivé — y compris quand l'utilisateur appuie sur Échap. C'est l'endroit idéal pour synchroniser l'interface :

Exemple :   📋 Copier le code

document.addEventListener('fullscreenchange', () => {
  if (document.fullscreenElement) {
    // Mode plein écran activé
    console.log('Plein écran :', document.fullscreenElement.id);
    bouton.textContent = '⛶ Quitter le plein écran';
  } else {
    // Retour au mode normal (Échap ou exitFullscreen)
    console.log('Retour au mode normal.');
    bouton.textContent = '⛶ Plein écran';
  }
});

// Détecter une erreur plein écran
document.addEventListener('fullscreenerror', () => {
  console.error('Le plein écran a été refusé.');
});

Styliser un élément en plein écran avec CSS

La pseudo-classe CSS ::backdrop et le sélecteur :fullscreen permettent de personnaliser l'apparence de l'élément une fois en plein écran :

Exemple :   📋 Copier le code

/* Styles appliqués à l'élément en plein écran */
#monContenu:fullscreen {
  background-color: #000;
  display: flex;
  align-items: center;
  justify-content: center;
}

/* Le fond derrière l'élément plein écran */
#monContenu::backdrop {
  background-color: rgba(0, 0, 0, 0.9);
}

Exemple pratique : lecteur vidéo avec bouton plein écran

Voici une implémentation complète d'un lecteur vidéo personnalisé avec contrôle du plein écran :

Exemple :   📋 Copier le code

const lecteur = document.getElementById('lecteur');
const video = lecteur.querySelector('video');
const btnLecture = lecteur.querySelector('.btn-lecture');
const btnFs = lecteur.querySelector('.btn-pleinecran');

// Lecture / pause
btnLecture.addEventListener('click', () => {
  video.paused ? video.play() : video.pause();
  btnLecture.textContent = video.paused ? '▶' : '⏸';
});

// Plein écran sur le lecteur entier (pas seulement la vidéo)
btnFs.addEventListener('click', async () => {
  if (!document.fullscreenElement) {
    await lecteur.requestFullscreen();
  } else {
    await document.exitFullscreen();
  }
});

// Mettre à jour l'icône selon l'état plein écran
document.addEventListener('fullscreenchange', () => {
  btnFs.textContent = document.fullscreenElement ? '⛶' : '⛶';
});

Vérifier la disponibilité de la Fullscreen API

Sur certains appareils ou contextes (iframes sans permission, anciens iOS), la Fullscreen API peut être indisponible. Un test rapide évite les erreurs silencieuses :

Exemple :   📋 Copier le code

// Vérifier que la Fullscreen API est disponible
if (document.fullscreenEnabled) {
  console.log('Fullscreen API disponible.');
  bouton.style.display = 'block';
} else {
  console.log('Fullscreen non supporté dans ce contexte.');
  bouton.style.display = 'none';
}

Bonnes pratiques

• Toujours déclencher depuis un geste utilisateur : requestFullscreen() échoue si elle n'est pas appelée dans un gestionnaire d'événement (clic, touche).
• Écouter fullscreenchange plutôt que de supposer l'état : l'utilisateur peut quitter le plein écran via Échap à tout moment.
• Vérifier document.fullscreenEnabled avant d'afficher le bouton plein écran — inutile de le montrer s'il ne fonctionnera pas.
• Préférer le plein écran sur un conteneur plutôt que sur la vidéo seule, pour inclure vos contrôles personnalisés dans la vue plein écran.

Par carabde | Mis à jour le 17 avril 2026