matchMedia()
Vérifie en JavaScript si la page satisfait une media query CSS, par exemple (max-width: 600px), et permet de réagir à ses changements.
- Renvoie
- Un objet
MediaQueryListavec les propriétésmatchesetmedia.
Exemple
#const mobile = matchMedia('(max-width: 600px)')
const prefersDark = matchMedia('(prefers-color-scheme: dark)')
console.log(mobile.media)
console.log(mobile.matches)
console.log(prefersDark.matches)
if (!mobile.matches) {
console.log('J’affiche le menu complet avec les noms des sections')
}(max-width: 600px) false true J’affiche le menu complet avec les noms des sections
Le résultat correspond à une fenêtre large sur un ordinateur avec le thème sombre du système activé. Sur un téléphone, mobile.matches vaut true. Le résultat dépend de l’appareil, donc cet exemple ne s’exécute pas dans l’aperçu.
Définition et utilisation
#La fonction matchMedia() (son nom complet est window.matchMedia()) prend une media query écrite comme une règle @media en CSS et renvoie un objet MediaQueryList. Sa propriété matches vaut true quand la condition est satisfaite, et media contient le texte de la requête. Vous vérifiez ainsi la largeur de la fenêtre, l’orientation de l’écran ou les préférences de l’utilisateur.
L’objet déclenche l’événement change chaque fois que le résultat de la requête change, par exemple quand l’utilisateur rétrécit la fenêtre sous un seuil ou passe le système en mode sombre. Vous branchez la gestion avec addEventListener("change", …), et l’objet événement a aussi un champ matches. C’est plus efficace que de vérifier window.innerWidth à chaque événement resize, car la fonction ne s’appelle qu’au franchissement du seuil.
Les requêtes sur les préférences sont particulièrement utiles : (prefers-color-scheme: dark) indique si le système utilise un thème sombre, et (prefers-reduced-motion: reduce), si l’utilisateur demande de limiter les animations. Il vaut la peine d’en tenir compte dans les scripts qui animent eux-mêmes des éléments ou choisissent le thème de la page.
Syntaxe
#window.matchMedia(mediaQueryString)
mediaQueryList.matches
mediaQueryList.media
mediaQueryList.addEventListener("change", listener)Paramètres
#mediaQueryString
chaîne
Une media query écrite comme en CSS, par ex."(max-width: 600px)"ou"(prefers-color-scheme: dark)".
Plus d’exemples
#const nav = document.querySelector('#nav')
const narrow = matchMedia('(max-width: 600px)')
function updateNav(query) {
nav.textContent = query.matches ? 'Menu ☰' : 'Cours · Classement · Profil · Réglages'
}
updateNav(narrow)
narrow.addEventListener('change', updateNav)
console.log('À l’écoute des changements :', narrow.media)Le contenu du menu dépend de la largeur du cadre de l’exemple. Rétrécissez ou élargissez la fenêtre du navigateur pour que le cadre franchisse 600 px, et le menu bascule tout seul, sans écouter l’événement resize.
const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)')
function scrollToTop() {
window.scrollTo({ top: 0, behavior: reduceMotion.matches ? 'auto' : 'smooth' })
}
console.log(reduceMotion.matches ? 'Défilement sans animation' : 'Défilement fluide')Défilement fluide
La plupart des gens n’ont pas activé la réduction des animations, donc vous verrez généralement ce résultat. Une fois la réduction des animations activée dans les réglages système, matches passe à true, et la page défile sans animation.
Compatibilité des navigateurs
#Largement disponible
Fonctionne dans tous les navigateurs modernes, y compris sur mobile. Vous pouvez l’utiliser sans crainte.
- Chrome
- Edge
- Firefox
- Safari
Bonnes pratiques
#- Pour réagir aux changements, utilisez
addEventListener("change", …). L’ancienne méthodeaddListener()est obsolète. - Gardez les seuils de largeur dans les scripts cohérents avec les points de rupture en CSS. Sinon, à la même largeur, le script et les styles peuvent se comporter différemment.
- Changez l’apparence elle-même en CSS avec
@media.matchMedia()est utile quand la logique dépend de la requête, par exemple pour activer une animation ou choisir quel composant afficher.
Entrées associées
#- getComputedStyle()Renvoie les styles calculés d’un élément, c’est-à-dire les valeurs CSS que le navigateur a réellement appliquées après avoir pris en compte toutes les règles.
- EventTarget.addEventListener()Enregistre une fonction appelée à chaque fois qu’un événement se produit sur un élément, par ex. un clic.
- ResizeObserverAppelle une fonction chaque fois que la taille d’un élément observé change, quelle qu’en soit la cause.
- Element.scrollIntoView()Fait défiler la page et les conteneurs défilants pour que l’élément apparaisse à l’écran, par un saut ou en douceur.
- Element.classListUn objet pour ajouter, retirer, basculer et vérifier les classes CSS d’un élément.
Vous voyez une erreur ou il manque un exemple ? Écrivez-nous.