# Custom units dans theme.json : au-delà du pixel pour l’espacement

> Proposer rem, vw ou % dans les contrôles d'espacement d'un thème bloc, sans se limiter au pixel par défaut : la clé custom units et ses limites actuelles, testées en conditions réelles.

- Auteur : Clément Hadrot
- Publié le : 2025-05-21
- Mis à jour le : 2025-05-21
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/custom-units-theme-json-espacement/

## L’essentiel

- customUnits ouvre les contrôles à plusieurs unités CSS
- Le choix reste au niveau du réglage, pas verrouillé par défaut
- Certaines unités posent des soucis de prévisualisation dans l'éditeur

Un intégrateur de notre équipe s'est vu demander, par un designer habitué à Figma, pourquoi les contrôles d'espacement du thème bloc en cours de développement n'affichaient que des pixels alors que la maquette raisonnait entièrement en `rem`. La réponse tenait à un réglage simple mais peu documenté de `theme.json` : la clé `settings.spacing.units`, qui contrôle précisément les unités disponibles dans les contrôles d'espacement de l'éditeur.

Ce réglage mérite d'être testé avant d'être généralisé à un thème en production : toutes les unités CSS valides ne se comportent pas de manière identique dans l'aperçu de l'éditeur, comme nous l'avons constaté sur ce projet.

## Activer plusieurs unités dans les contrôles

Par défaut, WordPress limite les unités proposées dans les contrôles de marge et de padding à un sous-ensemble restreint. La clé `settings.spacing.units` permet d'étendre explicitement cette liste :

```
{
  "version": 2,
  "settings": {
    "spacing": {
      "units": [ "px", "em", "rem", "vw", "%" ],
      "padding": true,
      "margin": true
    }
  }
}
```

Une fois cette liste déclarée, chaque contrôle d'espacement dans l'éditeur affiche un sélecteur d'unité permettant de basculer entre les valeurs listées, en plus du choix parmi les paliers de l'échelle d'espacement définie ailleurs dans `theme.json`.

## Ce que nous avons testé, unité par unité

> L'essentiel à retenir : customUnits ouvre les contrôles à plusieurs unités CSS ; Le choix reste au niveau du réglage, pas verrouillé par défaut ; Certaines unités posent des soucis de prévisualisation dans l'éditeur

Sur ce projet, nous avons testé les cinq unités les plus courantes pour évaluer leur fiabilité réelle dans l'éditeur :

- `px` et `rem` : comportement fiable, aperçu dans l'éditeur cohérent avec le rendu final en front.
- `em` : fonctionne, mais dépend du contexte d'imbrication du bloc, ce qui rend son usage imprévisible pour un rédacteur non averti.
- `vw` : techniquement accepté, mais l'aperçu dans l'éditeur ne reflète pas toujours fidèlement le rendu à différentes largeurs d'écran, faute de contexte de viewport identique entre l'admin et le front.
- `%` : dépend directement du conteneur parent, ce qui produit des résultats très différents selon le bloc dans lequel l'espacement est appliqué, un piège fréquent pour les rédacteurs qui changent un bloc de contexte.

## Notre recommandation à l'issue de ces tests

Nous avons finalement restreint la liste à trois unités seulement pour la mise en production : `px`, `rem` et `%`, en retirant `vw` et `em` jugées trop sujettes à un rendu incohérent entre éditeur et front pour une équipe rédactionnelle non technique. Proposer trop d'options à un utilisateur qui ne maîtrise pas les subtilités de chaque unité CSS crée davantage de confusion que de flexibilité utile.

> Une option technique correctement implémentée mais mal comprise par son utilisateur final finit toujours par générer plus de tickets de support que de gain de flexibilité réel.

## Le cas particulier des blocs individuels

La clé `settings.spacing.units` peut également être surchargée au niveau d'un bloc précis, dans la section `settings.blocks` de `theme.json`, pour restreindre ou étendre les unités disponibles uniquement pour ce bloc. Nous l'avons utilisé pour le bloc Colonnes, où `%` a plus de sens pour définir un espacement entre colonnes que pour un bloc Paragraphe isolé, où `rem` reste préférable.

## Limites actuelles à garder en tête

Cette fonctionnalité reste un réglage de contrôle d'interface : elle n'ajoute aucune validation qui empêcherait un rédacteur de saisir une valeur techniquement correcte mais visuellement problématique (un padding de `50vw`, par exemple). Le choix des unités proposées doit donc se faire en pensant d'abord à l'utilisateur final de l'éditeur, pas seulement aux possibilités offertes par la spécification CSS.

## En résumé

`settings.spacing.units` permet d'ouvrir les contrôles d'espacement d'un thème bloc à des unités plus adaptées à un design system moderne que le seul pixel par défaut. Mais chaque unité ajoutée doit être testée dans l'éditeur avant mise en production : certaines, comme `vw` ou `em`, introduisent des divergences entre l'aperçu admin et le rendu front qui peuvent dérouter une équipe rédactionnelle non technique.