Un développeur d’une coopérative agricole que j’accompagne butait depuis plusieurs semaines sur un problème récurrent : les styles d’ombre qu’il déclarait pour le bloc Bouton dans theme.json s’appliquaient au conteneur englobant du bouton plutôt qu’à l’élément visuel du bouton lui-même, produisant un rendu visuel incohérent que du CSS de contournement tentait tant bien que mal de corriger. Le sélecteur généré automatiquement par WordPress pour ce bloc ne correspondait tout simplement pas à l’élément qu’il fallait cibler pour cette propriété précise.
La version 6.3 de WordPress a introduit une réponse directe à ce type de problème avec l’API Selectors. Cet article détaille son usage pour un thème bloc. L’équivalent côté block.json, qui permet à l’auteur d’un bloc de déclarer ses propres sélecteurs par défaut, a été traité séparément et n’est pas repris ici.
Le problème que résout l’API Selectors
Par défaut, WordPress génère un sélecteur CSS automatique pour chaque bloc, basé sur sa classe racine, comme .wp-block-button. Pour un bloc structurellement simple comme un paragraphe, ce sélecteur correspond exactement à l’élément visuel attendu. Mais pour des blocs plus composés, comme le bloc Bouton dont l’élément cliquable réel est un enfant (.wp-block-button__link) niché à l’intérieur du conteneur racine, appliquer un style d’ombre ou de bordure au sélecteur racine par défaut produit un résultat visuellement différent de ce que l’auteur du theme.json avait en tête.
Déclarer un sélecteur personnalisé dans styles.blocks
La clé selectors, à l’intérieur de la déclaration de style d’un bloc dans styles.blocks, permet de remplacer le sélecteur par défaut pour l’ensemble du bloc, ou plus finement pour une sous-propriété de style précise.
{
"version": 2,
"styles": {
"blocks": {
"core/button": {
"shadow": "0px 4px 10px rgba(0, 0, 0, 0.2)"
}
}
}
}
Sans réglage spécifique, ce style d’ombre s’applique au sélecteur racine généré automatiquement. Pour cibler précisément l’élément lien interne, il faut ajouter une clé selectors à l’intérieur de la déclaration theme.json qui gère le sélecteur au niveau des metadata du support, pratique surtout utile quand le thème doit ajuster ce ciblage sans toucher au code source du bloc lui-même.
Un sélecteur distinct par sous-propriété
Le vrai gain de l’API Selectors apparaît quand plusieurs sous-propriétés d’un même bloc doivent cibler des éléments différents. Pour le bloc Bouton, la couleur de fond concerne logiquement l’élément lien interne, tandis qu’une marge extérieure éventuelle concerne plutôt le conteneur racine. La structure de selectors permet de préciser un sélecteur par sous-catégorie de style (root, color, typography, border, spacing), plutôt qu’un seul sélecteur global pour tout le bloc.
{
"styles": {
"blocks": {
"core/button": {
"color": {
"background": "#2f5233"
},
"border": {
"radius": "6px"
}
}
}
}
}
Sur ce projet, la coopérative agricole avait besoin d’un rayon de bordure appliqué uniquement au lien interne du bouton, tandis qu’un espacement extérieur devait rester porté par le conteneur racine pour ne pas perturber l’alignement du bloc dans une mise en page flexbox environnante. La déclaration fine de sélecteur par sous-propriété a permis de séparer proprement ces deux besoins, sans CSS de contournement additionnel.
Vérifier le CSS réellement généré
Pour valider qu’un sélecteur personnalisé produit bien l’effet attendu, j’inspecte systématiquement le style global généré par WordPress, consultable directement dans le code source de la page ou via l’API REST des styles globaux, plutôt que de me fier uniquement au rendu visuel dans l’éditeur, qui peut parfois différer légèrement du rendu final côté visiteur selon les feuilles de style additionnelles chargées.
curl -s https://exemple-cooperative.fr/wp-json/wp/v2/global-styles/1 | grep -o "wp-block-button[^;]*"
Ce que l’API Selectors ne remplace pas
Ce mécanisme reste réservé au CSS généré depuis theme.json pour les styles supportés nativement par le bloc concerné. Il ne permet pas de créer un style entièrement inédit sans rapport avec les propriétés déjà exposées par le bloc (couleur, bordure, espacement, typographie, ombre) : pour un besoin visuel hors de ce périmètre, une feuille de style complémentaire classique reste nécessaire, l’API Selectors ne visant qu’à mieux cibler ce qui est déjà pris en charge, pas à étendre le catalogue de propriétés disponibles.
En résumé
L’API Selectors, introduite en version 6.3, corrige une frustration réelle des développeurs de thème bloc : la possibilité de préciser, sous-propriété par sous-propriété, le sélecteur CSS réellement ciblé par un style déclaré dans theme.json, plutôt que de subir un sélecteur racine générique parfois inadapté à la structure interne du bloc concerné. C’est un raffinement technique précis, mais qui élimine une bonne partie du CSS de contournement autrefois nécessaire pour corriger ce genre de décalage.
