Une agence cliente vend des accessoires personnalisables et voulait afficher, directement dans le mini-panier, une pastille de couleur correspondant à l’option choisie par le client — sans passer par une extension tierce, et sans casser la mise à jour automatique du panier quand une quantité change. Ce genre de demande, en apparence simple, révèle vite une subtilité : WooCommerce dispose de deux systèmes de mini-panier bien distincts selon que le thème utilise l’ancien système de fragments AJAX ou le nouveau bloc panier basé sur l’Interactivity API.
Ce tutoriel couvre la personnalisation dans les deux contextes, avec un focus particulier sur l’Interactivity API, introduite dans WordPress 6.5 et de plus en plus utilisée par les thèmes de blocs récents pour les blocs panier et mini-panier.
Comprendre le système de fragments classique
Dans un thème classique, le mini-panier repose sur le filtre woocommerce_add_to_cart_fragments. Chaque fois qu’une action modifie le panier (ajout, suppression, changement de quantité), WooCommerce régénère en HTML les zones enregistrées comme fragments et les renvoie via AJAX, sans recharger la page. Ajouter un élément personnalisé consiste à s’accrocher à ce filtre pour injecter un fragment de plus, généralement un sélecteur CSS ciblant une zone du gabarit du mini-panier.
add_filter( 'woocommerce_add_to_cart_fragments', function( $fragments ) {
ob_start();
?>
<span class="pastille-couleur-panier">
<?php foreach ( WC()->cart->get_cart() as $item ) : ?>
<?php if ( ! empty( $item['couleur_choisie'] ) ) : ?>
<span style="background-color: <?php echo esc_attr( $item['couleur_choisie'] ); ?>"></span>
<?php endif; ?>
<?php endforeach; ?>
</span>
<?php
$fragments['span.pastille-couleur-panier'] = ob_get_clean();
return $fragments;
} );La donnée couleur_choisie doit elle-même avoir été ajoutée à l’article du panier via woocommerce_add_cart_item_data au moment de l’ajout au panier, en amont de cette personnalisation d’affichage.
Le cas du bloc panier et de l’Interactivity API
Les thèmes de blocs récents, à partir de Twenty Twenty-Four et suivants, proposent un bloc Mini-panier construit sur l’Interactivity API plutôt que sur des fragments AJAX classiques. La différence est fondamentale : l’état du panier vit dans un magasin d’état côté client (store), synchronisé avec le serveur via la Store API de WooCommerce, et le rendu se met à jour par liaison de données réactive plutôt que par remplacement de HTML complet.
Pour ajouter une information personnalisée dans ce contexte, il faut d’abord l’exposer côté serveur dans la réponse de la Store API, généralement via le filtre woocommerce_store_api_cart_item_response ou l’extension de schéma de la Store API prévue à cet effet, puis la consommer côté client dans un module qui étend le magasin d’état existant.
add_filter( 'woocommerce_store_api_cart_item_response', function( $item_data, $cart_item ) {
if ( ! empty( $cart_item['couleur_choisie'] ) ) {
$item_data['extensions']['agence-couleur'] = array(
'couleur' => sanitize_hex_color( $cart_item['couleur_choisie'] ),
);
}
return $item_data;
}, 10, 2 );Côté client, un module JavaScript enregistré avec store() depuis @wordpress/interactivity peut alors lire cette extension dans le contexte du bloc et l’afficher sans recharger l’ensemble du panier — seule la zone concernée se met à jour, ce qui évite le clignotement visuel typique des anciens fragments AJAX sur les paniers contenant beaucoup d’articles.
Le piège de l’état non isolé
Une erreur fréquente consiste à écrire directement dans l’état global du magasin panier plutôt que dans un contexte local au bloc personnalisé. Cela fonctionne en apparence, jusqu’à ce qu’un autre bloc interactif de la page (un compteur de quantité, un bouton de suppression) lise la même clé d’état et se comporte de façon imprévisible après l’ajout de la personnalisation. L’Interactivity API encourage explicitement l’usage de getContext() plutôt que store() global pour toute donnée propre à un bloc, précisément pour éviter ce genre de collision.
Choisir la bonne approche selon le thème
- Thème classique (non basé sur les blocs de site complet) : filtre
woocommerce_add_to_cart_fragments, approche éprouvée et bien documentée. - Thème de blocs avec bloc Mini-panier natif : extension de la Store API côté serveur, puis module Interactivity côté client.
- Dans les deux cas : ne jamais modifier le calcul du panier dans le code d’affichage — cette logique doit rester dans les hooks de calcul (
woocommerce_before_calculate_totals), jamais mélangée au rendu.
Le bloc Mini-panier récompense la discipline : tout ce qui touche à l’affichage doit rester dans le contexte du bloc, jamais dans l’état global. C’est contraignant au début, mais cela évite des heures de débogage sur des interactions qui se marchent dessus.
En résumé
Personnaliser le mini-panier n’est plus un geste unique depuis l’arrivée de l’Interactivity API : il faut désormais savoir sur quel système repose le thème avant d’écrire la moindre ligne de code. Les fragments AJAX classiques restent parfaitement valables sur les thèmes qui les utilisent encore, mais l’approche par blocs, plus récente, impose une discipline différente — extension de schéma côté serveur, état isolé côté client — qui, une fois comprise, ouvre la voie à des interfaces panier bien plus réactives.
