add_theme_support(‘custom-header’) : une image d’en-tête sans plugin

Trois paramètres suffisent la plupart du temps : une largeur, une hauteur, et l’autorisation ou non de recadrer l’image proposée par l’utilisateur. C’est tout ce que add_theme_support('custom-header') demande pour transformer une zone de bandeau figée en réglage accessible depuis le Customizer, sans qu’aucune extension ne soit nécessaire.

Pour un intégrateur qui livre un thème sur mesure, cette fonctionnalité change la relation avec le client final. Plutôt que de recevoir des demandes de modification par courriel à chaque campagne saisonnière, il suffit de renvoyer vers l’écran « Apparence > Personnaliser > En-tête ». Voici comment la mettre en place proprement, étape par étape.

Déclarer le support dans functions.php

La déclaration se fait dans le hook after_setup_theme, comme la plupart des fonctionnalités de thème. Elle prend un tableau d’arguments qui définit les dimensions attendues et le comportement du recadrage.

function monthème_setup() {
    add_theme_support( 'custom-header', array(
        'width'         => 1600,
        'height'        => 400,
        'flex-height'   => true,
        'flex-width'    => true,
        'header-text'   => false,
        'default-image' => get_template_directory_uri() . '/assets/images/header-defaut.jpg',
    ) );
}
add_action( 'after_setup_theme', 'monthème_setup' );

Le paramètre flex-height et flex-width autorisent l’utilisateur à envoyer une image dont les proportions diffèrent légèrement, sans blocage strict. header-text à false masque l’option d’afficher un texte par-dessus l’image, utile quand le logo est déjà géré ailleurs dans le thème.

Afficher l’en-tête dans le template

Une fois le support déclaré, deux fonctions suffisent pour restituer le résultat côté frontal : get_header_image() pour récupérer l’URL, et get_custom_header() pour obtenir l’objet complet avec largeur et hauteur.

<?php if ( get_header_image() ) : ?>
    <div class="site-header-image">
        <img src="<?php echo esc_url( get_header_image() ); ?>"
             width="<?php echo esc_attr( get_custom_header()->width ); ?>"
             height="<?php echo esc_attr( get_custom_header()->height ); ?>"
             alt="" />
    </div>
<?php endif; ?>

L’attribut alt vide est volontaire ici : une image de bandeau purement décorative n’a pas besoin d’être annoncée par un lecteur d’écran. Si l’image porte un message informatif, remplacez-le par un texte pertinent.

Proposer plusieurs en-têtes par défaut

Il est possible d’aller plus loin en proposant une bibliothèque d’images par défaut, parmi lesquelles l’utilisateur choisit sans avoir à en envoyer une lui-même. Cela rassure les clients qui n’ont pas de visuel prêt le jour de la mise en ligne.

• Déclarer un tableau default-image pointant vers un fichier situé dans le thème.
• Ajouter un filtre sur default_headers pour proposer un choix parmi plusieurs images.
• Fournir des vignettes de prévisualisation cohérentes en taille avec l’image finale.

function monthème_headers_par_defaut() {
    register_default_headers( array(
        'ciel' => array(
            'url'           => '%s/assets/images/header-ciel.jpg',
            'thumbnail_url' => '%s/assets/images/header-ciel-thumb.jpg',
            'description'   => 'Ciel dégagé',
        ),
    ) );
}
add_action( 'after_setup_theme', 'monthème_headers_par_defaut' );

Les pièges à connaître

Le premier piège concerne le recadrage : si flex-height et flex-width ne sont pas activés, WordPress impose un recadrage strict aux dimensions exactes déclarées, ce qui peut surprendre un client qui envoie une photo au format différent sans prévenir.

Le second piège touche la performance. L’image de bandeau étant souvent la plus grande ressource visuelle de la page, il est recommandé de vérifier qu’elle passe par le système de tailles d’image de WordPress plutôt que d’être servie en pleine résolution d’origine. Un contrôle via wp_get_attachment_image_src() sur l’ID retourné par get_custom_header() permet de choisir une taille adaptée.

Sur nos projets, systématiser cette fonctionnalité pour tout bandeau destiné à changer plus d’une fois par an nous a fait gagner un temps considérable en maintenance : le client modifie lui-même, sans ticket.

En résumé

L’en-tête personnalisé reste l’une des fonctionnalités de thème les plus sous-utilisées alors qu’elle demande très peu de code. Bien réglée, avec des dimensions flexibles et une image par défaut de qualité, elle évite des demandes récurrentes tout en gardant un contrôle propre sur le rendu visuel du site.