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

> Comment déclarer un en-tête personnalisable dans un thème classique, pour qu'un client change son image de bandeau sans toucher au code ni installer une extension.

- Auteur : WordPress Développement
- Publié le : 2020-01-05
- Mis à jour le : 2020-01-05
- Catégorie : Thèmes
- URL : https://www.wpmoderne.fr/themes/add-theme-support-custom-header-image-entete-sans-plugin/

## L’essentiel

- Une seule déclaration active tout le mécanisme
- Le Customizer gère l'upload et le recadrage
- Un filtre permet un rendu par défaut soigné

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.

> L'essentiel à retenir : Une seule déclaration active tout le mécanisme ; Le Customizer gère l'upload et le recadrage ; Un filtre permet un rendu par défaut soigné

## 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.