Compositions de blocs WordPress (patterns) : créer, enregistrer, synchroniser
Un bandeau d'accueil, une grille de tarifs, un pied de page avec trois colonnes : la plupart des sections d'un site se répètent d'une page à l'autre. Dans WordPress, ces assemblages de blocs prêts à l'emploi s'appellent des compositions (patterns en anglais). Bien conçues, elles font gagner du temps et gardent un site cohérent ; mal comprises, elles donnent des pages qu'on croit liées et qui ne le sont pas. Voici comment elles fonctionnent et comment les fabriquer proprement.
Composition, partie de gabarit, bloc : ne pas confondre
Un thème blocs dispose de trois briques qui se ressemblent. Le bloc est l'unité de base : un paragraphe, une image, un bouton. La partie de gabarit (template part), rangée dans le dossier parts/, est une zone de structure comme l'en-tête ou le pied de page, partagée par tous les gabarits qui l'appellent. La composition, enfin, est un assemblage de blocs proposé à l'insertion, que l'auteur d'une page place où il veut. Nous avons présenté l'organisation générale de ces dossiers dans notre article sur le fonctionnement d'un thème blocs.
La distinction compte en pratique : modifier une partie de gabarit change toutes les pages qui l'utilisent, alors qu'une composition ordinaire ne laisse dans la page qu'une copie de ses blocs, sans lien avec l'original.
Synchronisée ou non : la question à se poser d'abord
Depuis WordPress 6.3, l'éditeur propose deux sortes de compositions créées par l'utilisateur. Les compositions non synchronisées servent de point de départ : une fois insérées, leurs blocs appartiennent à la page et se modifient librement. Les compositions synchronisées, qui remplacent les anciens blocs réutilisables, restent liées à une source unique, enregistrée en base de données dans le type de contenu wp_block : corriger le texte d'un encart synchronisé le corrige sur toutes les pages qui l'affichent.
WordPress 6.6 a ajouté une voie intermédiaire, les remplacements (overrides) : la mise en forme d'une composition synchronisée reste commune, mais certains blocs désignés peuvent recevoir un contenu propre à chaque page. Une carte « membre de l'équipe » peut ainsi garder la même présentation partout, avec un nom et une photo différents à chaque usage. Le mécanisme repose sur l'API de liaison de blocs (Block Bindings) et ne concerne qu'un petit nombre de blocs du cœur, comme le paragraphe, le titre, l'image ou le bouton.
| Besoin | Choix adapté |
|---|---|
| Une mise en page de départ que chaque page adaptera | Composition non synchronisée |
| Un encart identique partout (mention, appel à l'action, horaires) | Composition synchronisée |
| Une présentation commune, un contenu propre à chaque page | Composition synchronisée avec remplacements |
| Une zone présente sur toutes les pages (en-tête, pied) | Partie de gabarit |
Déclarer une composition dans un thème
Le manuel des thèmes décrit deux méthodes, à ne pas mélanger pour une même composition : un fichier dans le dossier /patterns, ou un appel à register_block_pattern() en PHP sur le crochet init. La première est la plus simple : WordPress enregistre automatiquement tout fichier PHP de ce dossier dont l'en-tête est valide.
<?php
/**
* Title: Bandeau d'appel
* Slug: montheme/bandeau-appel
* Categories: banner, call-to-action
* Keywords: accueil, contact, rendez-vous
* Viewport Width: 1200
*/
?>
<!-- wp:group {"align":"full","layout":{"type":"constrained"}} -->
<div class="wp-block-group alignfull">
<!-- wp:heading -->
<h2 class="wp-block-heading"><?php esc_html_e( 'Parlons de votre projet', 'montheme' ); ?></h2>
<!-- /wp:heading -->
<!-- wp:paragraph -->
<p><?php esc_html_e( 'Réponse sous deux jours ouvrés.', 'montheme' ); ?></p>
<!-- /wp:paragraph -->
</div>
<!-- /wp:group -->Seuls Title et Slug sont indispensables. Les autres champs de l'en-tête affinent l'usage :
- Categories range la composition dans une ou plusieurs catégories de l'outil d'insertion ; un thème peut créer les siennes avec
register_block_pattern_category(), en préfixant leur nom par celui du thème. - Keywords ajoute des mots pour la recherche ; Description n'est lue que par les lecteurs d'écran.
- Viewport Width fixe la largeur, en pixels, de l'aperçu affiché dans l'outil d'insertion.
- Block Types associe la composition à des types de blocs ; avec
core/post-content, elle est proposée comme modèle de départ à la création d'une nouvelle page. - Post Types limite les types de contenu où elle apparaît, et Template Types les types de gabarits auxquels elle convient.
- Inserter: no cache la composition de l'outil d'insertion : utile pour un morceau appelé seulement depuis un gabarit.
Traduire et sécuriser le contenu
Parce que le fichier est en PHP, ses textes peuvent passer par les fonctions de traduction de WordPress. Le manuel recommande esc_html_e() pour le texte, qui échappe la sortie en la rendant traduisible, et esc_url( get_theme_file_uri( … ) ) pour les images livrées avec le thème. Une composition écrite « en dur » en français ne pourra jamais être traduite par un fichier de langue ; c'est un défaut fréquent des thèmes adaptés à la hâte.
Les compositions de l'utilisateur et celles du répertoire
Un utilisateur peut aussi créer ses propres compositions depuis l'éditeur, en sélectionnant des blocs puis en choisissant « Créer une composition ». Elles sont stockées en base, pas dans le thème : changer de thème ne les fait pas disparaître, mais elles ne voyagent pas non plus avec lui. Pour qu'une composition fasse partie d'un thème diffusé, il faut la reporter dans le dossier /patterns.
WordPress charge en outre par défaut des compositions venues du répertoire public de WordPress.org. Un thème qui veut garder la maîtrise de ce que voient ses utilisateurs peut couper ce chargement distant avec le filtre should_load_remote_block_patterns renvoyant __return_false. À l'inverse, theme.json peut lister des compositions du répertoire à proposer, par leur identifiant ; ce fichier et ses autres sections sont détaillés dans notre guide pratique de theme.json.
Six règles pour des compositions qui durent
- Utiliser les préréglages du thème. Couleurs, tailles de police et espacements doivent venir des valeurs de
theme.json, pas de codes hexadécimaux ou de pixels écrits dans les attributs des blocs : une variation de style pourra alors changer l'apparence de toutes les compositions d'un coup. - Garder des slugs stables. Renommer le
Slugd'une composition casse les gabarits qui l'appellent par son nom, et un thème enfant qui veut la remplacer doit reprendre exactement le même. - Respecter la hiérarchie des titres. Une composition ne sait pas où elle sera insérée : un bandeau qui commence par un titre de niveau 1 crée un second
h1sur la page. - Prévoir des images neutres et légères. Les photos livrées avec le thème pèsent sur chaque installation ; leur licence doit permettre la redistribution.
- Remplir les textes alternatifs, ou les laisser vides à dessein. Une image décorative a un
altvide ; une image informative a une alternative pertinente. La liste complète des points à contrôler figure dans notre article sur les thèmes accessibles. - Ne pas synchroniser par réflexe. Une composition synchronisée modifiée par erreur se modifie partout. Réserver la synchronisation aux contenus vraiment identiques.
Bon réflexe
- Avant de livrer un site, ouvrir l'outil d'insertion, onglet Compositions, et vérifier que chaque composition du thème s'affiche correctement en aperçu, en clair comme en sombre si le thème propose plusieurs variations.
- Documenter pour le client quelles compositions sont synchronisées : c'est la première source de surprises après la mise en ligne.
Sources
- WordPress Developer Resources, Theme Handbook, « Block Patterns » (consulté le 4 novembre 2026).
- WordPress Developer Blog, « An introduction to overrides in synced patterns », juin 2024.
Thèmes & WordPressLe thème blocs, comment ça marche
Deux fichiers obligatoires, des gabarits en HTML, un éditeur de site : ce qui change quand un thème WordPress est construit entièrement en blocs.
Thèmes & WordPresstheme.json, le guide pratique
Version, settings, styles, préréglages et variables CSS : comment un seul fichier JSON pilote l'apparence d'un thème blocs.
Thèmes & WordPressVariation de style ou thème enfant ?
Changer une palette, ajuster un gabarit, ou refaire le thème : trois niveaux de personnalisation, trois outils différents.