Balise <details> HTML : créer des contenus dépliables

Introduction à la balise <details>

La balise <details> est l'un des éléments HTML les plus pratiques pour créer des contenus interactifs sans avoir recours à JavaScript. Elle permet de concevoir des sections dépliables que vos utilisateurs peuvent ouvrir ou fermer d'un simple clic, améliorant ainsi considérablement l'expérience utilisateur sur vos pages web.

Si vous souhaitez maîtriser parfaitement HTML et toutes ses balises interactives, notre formation pour apprendre HTML vous accompagne pas à pas dans la création de sites web modernes et accessibles. Vous y découvrirez comment utiliser efficacement des éléments comme <details> pour enrichir vos interfaces.

Cette balise est particulièrement utile pour les FAQ, les menus accordéon, les sections d'aide contextuelle ou tout contenu que vous souhaitez masquer par défaut pour ne pas surcharger votre page. Nous allons explorer ensemble toutes les possibilités qu'elle offre.

Définition et syntaxe de la balise <details>

Qu'est-ce que la balise <details> ?

La balise <details> est un élément HTML5 sémantique qui crée un widget de divulgation (disclosure widget). Ce widget permet d'afficher ou de masquer des informations supplémentaires. Par défaut, le contenu à l'intérieur de <details> est masqué, et l'utilisateur doit cliquer pour le révéler.

Cette balise fonctionne en tandem avec la balise <summary> qui définit le titre visible et cliquable de l'élément. Sans <summary>, le navigateur affiche un texte par défaut comme "Détails".

Syntaxe de base

Voici la structure fondamentale de la balise <details> :

<details>
  <summary>Cliquez pour en savoir plus</summary>
  <p>Voici le contenu caché qui apparaît quand on déplie l'élément.</p>
</details>

Dans cet exemple, seul le texte "Cliquez pour en savoir plus" est visible initialement. Le paragraphe ne s'affiche que lorsque l'utilisateur interagit avec l'élément.

Attributs disponibles

La balise <details> accepte plusieurs attributs importants :

L'attribut open

L'attribut open permet d'afficher le contenu déplié dès le chargement de la page :

<details open>
  <summary>Section déjà ouverte</summary>
  <p>Ce contenu est visible immédiatement au chargement de la page.</p>
</details>

Exemples pratiques d'utilisation

Créer une FAQ interactive

L'un des cas d'usage les plus courants de <details> est la création de FAQ (Foire Aux Questions). Voici comment structurer une FAQ pour votre site Believemy :

<section class="faq-believemy">
  <h2>Questions fréquentes sur nos formations</h2>
  
  <details>
    <summary>Comment accéder à ma formation ?</summary>
    <p>Après votre inscription, vous recevez un email de confirmation 
    avec vos identifiants. Connectez-vous ensuite à votre espace 
    apprenant pour accéder à tous vos cours.</p>
  </details>
  
  <details>
    <summary>Les formations sont-elles accessibles à vie ?</summary>
    <p>Oui ! Une fois inscrit, vous gardez un accès illimité à votre 
    formation ainsi qu'à toutes les mises à jour futures.</p>
  </details>
  
  <details>
    <summary>Puis-je obtenir un certificat ?</summary>
    <p>Absolument. À la fin de chaque formation, vous pouvez 
    télécharger votre certificat de réussite personnalisé.</p>
  </details>
</section>

Cette structure est parfaitement sémantique et accessible. Les moteurs de recherche peuvent indexer le contenu, et les lecteurs d'écran gèrent nativement ce type d'élément.

Créer un menu accordéon

Depuis 2023, l'attribut name permet de créer des groupes d'éléments <details> où un seul peut être ouvert à la fois. C'est le comportement typique d'un accordéon :

<div class="accordeon-formation">
  <details name="modules-html">
    <summary>Module 1 : Les bases du HTML</summary>
    <ul>
      <li>Introduction au web</li>
      <li>Structure d'une page HTML</li>
      <li>Les balises essentielles</li>
    </ul>
  </details>
  
  <details name="modules-html">
    <summary>Module 2 : Les formulaires</summary>
    <ul>
      <li>La balise form</li>
      <li>Les champs de saisie</li>
      <li>Validation des données</li>
    </ul>
  </details>
  
  <details name="modules-html">
    <summary>Module 3 : HTML sémantique</summary>
    <ul>
      <li>L'importance de la sémantique</li>
      <li>Les balises structurelles</li>
      <li>Accessibilité et SEO</li>
    </ul>
  </details>
</div>

Lorsque vous ouvrez un module, les autres se ferment automatiquement. Cette fonctionnalité est native et ne nécessite aucun JavaScript !

Afficher du code source

Pour les tutoriels et la documentation technique, <details> est idéal pour masquer de longs blocs de code :

<details>
  <summary>Voir le code source complet</summary>
  <pre><code class="language-javascript">
function calculerPrixFormation(prixBase, reduction) {
  const prixFinal = prixBase * (1 - reduction / 100);
  return prixFinal.toFixed(2);
}

const prix = calculerPrixFormation(299, 20);
console.log(`Prix après réduction : ${prix}€`);
  </code></pre>
</details>

Cette approche permet de garder vos articles lisibles tout en offrant le code complet aux lecteurs intéressés.

Personnalisation CSS de la balise <details>

Styliser le résumé et le marqueur

Le pseudo-élément ::marker permet de personnaliser la flèche ou le triangle qui indique l'état ouvert/fermé :

/* Styliser le summary */
details summary {
  cursor: pointer;
  padding: 1rem;
  background-color: #f5f5f5;
  border-radius: 8px;
  font-weight: 600;
  list-style: none; /* Retire le marqueur par défaut */
}

/* État au survol */
details summary:hover {
  background-color: #e8e8e8;
}

/* Personnaliser le marqueur */
details summary::marker {
  color: #3498db;
  font-size: 1.2em;
}

/* Alternative : utiliser ::before pour un marqueur personnalisé */
details summary::before {
  content: '▶ ';
  display: inline-block;
  transition: transform 0.3s ease;
}

details[open] summary::before {
  transform: rotate(90deg);
}

Animer l'ouverture et la fermeture

L'animation du contenu de <details> est délicate car le navigateur gère l'affichage de manière binaire. Voici une technique utilisant les grilles CSS :

details {
  border: 1px solid #ddd;
  border-radius: 8px;
  margin-bottom: 1rem;
  overflow: hidden;
}

details summary {
  padding: 1rem 1.5rem;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  cursor: pointer;
}

details .contenu-details {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 0.3s ease-out;
}

details[open] .contenu-details {
  grid-template-rows: 1fr;
}

details .contenu-details > div {
  overflow: hidden;
}

details .contenu-details > div > * {
  padding: 1rem 1.5rem;
}

Et le HTML correspondant :

<details>
  <summary>Découvrir le programme</summary>
  <div class="contenu-details">
    <div>
      <p>Notre formation HTML couvre tous les aspects essentiels...</p>
    </div>
  </div>
</details>

Accessibilité et bonnes pratiques

Accessibilité native

La balise <details> est intrinsèquement accessible. Les technologies d'assistance reconnaissent cet élément et informent les utilisateurs qu'il s'agit d'un contenu dépliable. Voici les caractéristiques d'accessibilité natives :

• Les lecteurs d'écran annoncent l'état (développé ou réduit)
• La navigation au clavier fonctionne avec la touche Entrée ou Espace
• Le focus est correctement géré
• L'élément est dans l'arbre d'accessibilité du navigateur

Bonnes pratiques à suivre

Pour garantir une expérience optimale, respectez ces recommandations :

Considérations SEO

Le contenu à l'intérieur de <details> est présent dans le DOM et donc indexable par les moteurs de recherche. Google a confirmé que ce contenu est pris en compte pour le référencement, même s'il est visuellement masqué. C'est un avantage majeur par rapport aux solutions JavaScript qui pourraient ne pas charger le contenu immédiatement.

Événements JavaScript avec <details>

Détecter l'ouverture et la fermeture

Vous pouvez écouter l'événement toggle pour réagir aux changements d'état :

const detailsElement = document.querySelector('details.formation-believemy');

detailsElement.addEventListener('toggle', (event) => {
  if (detailsElement.open) {
    console.log('La section a été ouverte');
    // Vous pouvez par exemple charger du contenu dynamique
    // ou envoyer un événement analytics
  } else {
    console.log('La section a été fermée');
  }
});

Contrôler l'état programmatiquement

Vous pouvez ouvrir ou fermer un élément <details> via JavaScript :

const details = document.getElementById('ma-section');

// Ouvrir
details.open = true;

// Fermer
details.open = false;

// Basculer l'état
details.open = !details.open;

// Fonction utilitaire pour tout ouvrir ou fermer
function toggleAllDetails(ouvert) {
  document.querySelectorAll('details').forEach(detail => {
    detail.open = ouvert;
  });
}

// Ouvrir tous les détails
toggleAllDetails(true);

// Fermer tous les détails
toggleAllDetails(false);

Erreurs fréquentes à éviter

Oublier la balise summary

Sans <summary>, le navigateur utilise un texte par défaut :

<!-- ❌ À éviter -->
<details>
  <p>Contenu sans résumé explicite</p>
</details>

<!-- ✅ Correct -->
<details>
  <summary>En savoir plus sur ce sujet</summary>
  <p>Contenu avec un résumé clair</p>
</details>

Mauvais placement du summary

Le <summary>https://believemy.com/fr/glossaires/html-et-css/summary doit être le premier enfant de <details> :

<!-- ❌ Incorrect -->
<details>
  <p>Du contenu avant</p>
  <summary>Le résumé</summary>
</details>

<!-- ✅ Correct -->
<details>
  <summary>Le résumé</summary>
  <p>Le contenu après</p>
</details>

Utiliser details pour du contenu critique

Ne masquez pas d'informations essentielles que l'utilisateur doit absolument voir :

<!-- ❌ À éviter : information critique masquée -->
<details>
  <summary>Conditions importantes</summary>
  <p>Attention : votre commande sera annulée si non payée sous 24h.</p>
</details>

<!-- ✅ Mieux : information visible directement -->
<p class="alerte">⚠️ Votre commande sera annulée si non payée sous 24h.</p>

Compatibilité navigateurs

La balise <details> bénéficie d'un excellent support dans les navigateurs modernes :

Questions fréquentes sur la balise <details>

Oui, vous pouvez imbriquer des éléments <details>, mais nous vous recommandons de ne pas dépasser deux niveaux d'imbrication pour maintenir une bonne expérience utilisateur. Chaque niveau doit avoir son propre <summary> descriptif.

Oui, Google indexe le contenu présent dans les balises <details> même s'il est visuellement masqué. Le contenu étant présent dans le DOM dès le chargement de la page, il est accessible aux robots d'indexation. C'est un avantage significatif pour le SEO de vos FAQ et contenus dépliables.

Utilisez l'attribut name avec la même valeur sur plusieurs éléments <details>. Le navigateur fermera automatiquement les autres éléments du groupe lorsqu'un nouvel élément est ouvert. Cette fonctionnalité est supportée par les navigateurs modernes depuis 2023.

Pour maîtriser HTML, CSS et toutes les balises interactives comme <details>, nous vous recommandons de suivre notre formation pour apprendre HTML. Cette formation vous guide pas à pas dans la création de sites web modernes, accessibles et optimisés pour le référencement.