# L’API selectors de block.json : cibler le CSS généré par vos supports

> Depuis WordPress 6.3, la clé selectors de block.json permet d'indiquer précisément où appliquer les styles générés par les supports, sans hack CSS après coup.

- Auteur : Clément Hadrot
- Publié le : 2023-12-07
- Mis à jour le : 2023-12-07
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/block-json-selectors-cibler-css-supports/

## L’essentiel

- selectors remplace les sélecteurs devinés par défaut sur la racine du bloc
- Chaque feature de support peut cibler un sélecteur différent
- Indispensable pour les blocs au balisage interne complexe

Un bloc « Carte info » développé en interne posait un problème récurrent : la couleur de fond choisie dans l'inspecteur (via le support `color.background`) s'appliquait sur le conteneur racine du bloc, alors que le design demandait qu'elle ne colore que le bandeau supérieur interne. La solution habituelle avant WordPress 6.3 consistait à surcharger la classe générée en CSS, avec un sélecteur plus spécifique qui annulait le style inline injecté par l'éditeur — fragile, et perdu dès qu'une nouvelle version de WordPress changeait légèrement la structure de classes.

La clé `selectors` de `block.json`, introduite dans WordPress 6.3 (août 2023), règle ce problème à la source : elle indique explicitement à Gutenberg où injecter le CSS généré par chaque support, sans devoir deviner ni surcharger quoi que ce soit après coup.

## Le comportement par défaut, et sa limite

Sans `selectors`, tous les styles générés par les supports (couleur, typographie, marges, bordures) s'appliquent sur l'élément racine du bloc, celui qui reçoit les classes et attributs de `useBlockProps()` côté éditeur et le wrapper équivalent côté rendu serveur. Pour un bloc simple à un seul niveau de balisage, c'est exactement ce qu'il faut. Pour un bloc au balisage interne plus riche — une carte avec en-tête, corps et pied, par exemple — ce comportement uniforme devient une contrainte de design.

## Déclarer des sélecteurs par fonctionnalité

La clé `selectors` se déclare au niveau racine de `block.json`, avec une entrée par groupe de support (`color`, `typography`, `spacing`, `border`...), et peut même descendre au niveau d'une sous-fonctionnalité précise comme `color.background` ou `color.text` :

```
{
    "apiVersion": 3,
    "name": "agence/carte-info",
    "title": "Carte info",
    "supports": {
        "color": {
            "background": true,
            "text": true
        },
        "spacing": {
            "padding": true
        }
    },
    "selectors": {
        "color": {
            "background": ".agence-carte-info__bandeau",
            "text": ".agence-carte-info__corps"
        },
        "spacing": {
            "padding": ".agence-carte-info__corps"
        }
    }
}
```

Avec cette déclaration, choisir une couleur de fond dans l'inspecteur génère désormais une règle CSS ciblant `.agence-carte-info__bandeau`, tandis que le padding s'applique à `.agence-carte-info__corps` — deux éléments distincts du même bloc, chacun stylé indépendamment par les réglages natifs de l'éditeur.

## Adapter le rendu PHP en conséquence

Côté `render.php`, il faut que le balisage produit contienne effectivement ces classes aux bons emplacements. `selectors` ne génère aucun HTML : il indique seulement où le CSS doit s'appliquer, à charge pour le développeur de faire correspondre le balisage.

```
<?php
$wrapper_attributes = get_block_wrapper_attributes();
?>
<div <?php echo $wrapper_attributes; ?>>
    <div class="agence-carte-info__bandeau">
        <?php echo esc_html( $attributes['titre'] ?? '' ); ?>
    </div>
    <div class="agence-carte-info__corps">
        <?php echo wp_kses_post( $attributes['contenu'] ?? '' ); ?>
    </div>
</div>
```

> L'essentiel à retenir : selectors remplace les sélecteurs devinés par défaut sur la racine du bloc ; Chaque feature de support peut cibler un sélecteur différent ; Indispensable pour les blocs au balisage interne complexe

## Sélecteurs racine explicites

Une entrée `root` permet aussi de rediriger l'ensemble du wrapper généré par `useBlockProps` vers un sélecteur personnalisé, utile quand le bloc a besoin d'un élément racine qui n'est pas le `div` attendu par défaut :

```
{
    "selectors": {
        "root": ".agence-carte-info"
    }
}
```

## Ce que selectors ne remplace pas

Cette API concerne uniquement le CSS généré automatiquement par les supports déclarés dans `block.json` — couleurs, typographie, espacement, bordures, ombres. Elle ne remplace pas les classes de blocs génériques (`wp-block-agence-carte-info`), toujours présentes, ni les styles personnalisés écrits à la main dans une feuille CSS du bloc, qui continuent de cibler les sélecteurs de leur choix indépendamment. `selectors` ne s'applique pas non plus aux propriétés issues de `theme.json` pour les éléments génériques (liens, boutons) : cette clé reste circonscrite aux supports d'un bloc donné.

### Vérifier le résultat

Pour valider la configuration, on inspecte simplement l'attribut `style` injecté sur le bloc dans l'éditeur après avoir changé une couleur : avant 6.3 il apparaît sur le conteneur racine, après une déclaration `selectors` correcte il apparaît en attribut `style` sur une règle CSS générée ciblant la classe indiquée (WordPress injecte une feuille de style dédiée avec un sélecteur basé sur l'ID du bloc, pas un style inline direct, ce qui permet la spécificité voulue).

> Un piège rencontré sur ce projet : oublier de mettre à jour le balisage du `save()` côté JavaScript pour les blocs statiques, en ne corrigeant que le `render.php`. Résultat, l'aperçu dans l'éditeur ne correspondait plus au rendu front tant que les deux fichiers n'étaient pas alignés.

## En résumé

La clé `selectors` de `block.json` transforme un problème auparavant résolu à coups de CSS de contournement en une simple déclaration structurée, alignée avec le balisage réel du bloc. Dès qu'un bloc a plusieurs niveaux de structure interne et que les supports natifs doivent cibler des éléments différents, cette API évite des heures de débogage de spécificité CSS — à condition de garder le rendu `edit()` et `render.php` parfaitement synchronisés.