useViewportMatch adapte l’aperçu d’un bloc à la taille d’écran choisie

import { useViewportMatch } from '@wordpress/compose'; : cette ligne suffit à démarrer un besoin fréquent dans l’éditeur de blocs, celui d’adapter l’aperçu d’un bloc selon le mode de prévisualisation choisi par le rédacteur (ordinateur, tablette ou mobile), sans se contenter d’une media query CSS classique qui réagirait à la fenêtre réelle du navigateur.

Ce guide détaille comment ce hook fonctionne, en quoi il diffère d’une simple détection de largeur, et comment l’utiliser pour afficher, par exemple, une barre d’outils simplifiée quand l’éditeur simule un petit écran.

Étape 1 : comprendre ce que simule l’éditeur

Depuis plusieurs versions, l’éditeur de blocs propose un sélecteur de type d’aperçu (ordinateur, tablette, mobile) qui redimensionne visuellement le canevas d’édition, sans changer la taille réelle de la fenêtre du navigateur. Une media query CSS classique, basée sur window.innerWidth, ne détecte pas ce changement : elle continue de refléter la taille réelle de l’écran de l’ordinateur du rédacteur.

useViewportMatch résout ce problème en interrogeant l’état interne de l’éditeur plutôt que le navigateur, ce qui permet à un bloc de réagir correctement à la simulation choisie.

Étape 2 : utiliser le hook dans un composant Edit

import { useViewportMatch } from '@wordpress/compose';

function Edit() {
    const estMobile = useViewportMatch( 'small', '<' );

    return (
        <div>
            { estMobile
                ? <p>Aperçu simplifié pour petit écran</p>
                : <p>Aperçu complet avec toutes les options</p> }
        </div>
    );
}

Le premier argument désigne le point de rupture (mobile, small, medium, large, wide, huge), le second l’opérateur de comparaison (<, >=, etc.). Par défaut, sans second argument, le hook considère l’opérateur >=.

Étape 3 : combiner plusieurs points de rupture

Un bloc peut avoir besoin de plusieurs seuils simultanément, par exemple pour masquer une colonne entière sous une certaine largeur et simplifier une barre d’outils sous une autre :

function Edit() {
    const ecranMoyenOuPlus = useViewportMatch( 'medium' );
    const ecranTresEtroit = useViewportMatch( 'mobile', '<' );

    return (
        <div>
            { ecranMoyenOuPlus && <ColonneLaterale /> }
            { ecranTresEtroit && <p>Vue compacte</p> }
        </div>
    );
}

Chaque appel du hook est indépendant : il n’y a pas de limite au nombre d’instances utilisées dans un même composant, tant que chacune sert un usage distinct et documenté.

Étape 4 : éviter la confusion avec le rendu côté front

• useViewportMatch n’a aucun effet sur le rendu final publié sur le site : il agit uniquement dans l’éditeur.
• Pour un comportement responsive côté visiteur, il faut passer par des media queries CSS classiques dans la feuille de style du bloc, déclarée via style dans block.json.
• Confondre les deux mécanismes conduit à des blocs qui semblent responsives dans l’éditeur mais ne le sont pas du tout une fois publiés.

Étape 5 : un cas concret, la barre d’outils adaptative

Un bloc « galerie avancée » propose en temps normal cinq boutons dans sa barre d’outils : alignement, disposition en grille ou en carrousel, légendes, zoom, et partage. Sur un aperçu mobile simulé, cette barre déborde visuellement. En combinant useViewportMatch avec un menu déroulant DropdownMenu des composants WordPress, seuls les deux boutons les plus utilisés restent visibles directement, les autres basculant dans le menu :

const vueEtroite = useViewportMatch( 'medium', '<' );

return vueEtroite ? <BarreCompacte /> : <BarreComplete />;

Ce genre d’adaptation améliore concrètement le confort d’édition d’un bloc riche en options, sans jamais toucher au rendu final du site.

Sur nos blocs les plus riches en réglages, on réserve systématiquement une passe de test avec chaque mode d’aperçu de l’éditeur avant la livraison : c’est souvent là qu’apparaissent les débordements visuels que useViewportMatch permet justement d’éviter.

En résumé

useViewportMatch comble un besoin précis : synchroniser l’apparence d’un bloc avec le mode d’aperçu choisi dans l’éditeur, indépendamment de la taille réelle de la fenêtre du navigateur. Associé à une barre d’outils ou à un panneau de réglages, il évite bien des interfaces d’édition encombrées sur les aperçus les plus étroits.