<details> : l'élément de divulgation des détails

Exemple interactif

<details>
  <summary>Détails</summary>
  Quelque chose d'assez discret pour passer inaperçu.
</details>

details {
  border: 1px solid #aaaaaa;
  border-radius: 4px;
  padding: 0.5em 0.5em 0;
}

summary {
  font-weight: bold;
  margin: -0.5em -0.5em 0;
  padding: 0.5em;
}

details[open] {
  padding: 0.5em;
}

details[open] summary {
  border-bottom: 1px solid #aaaaaa;
  margin-bottom: 0.5em;
}

Un composant <details> peut être dans l'un des deux états. L'état par défaut fermé affiche uniquement le triangle et l'étiquette à l'intérieur de <summary> (ou une chaîne par défaut définie par agent utilisateur si aucun <summary> n'est présent).

Lorsque l'utilisateur·ice clique sur le composant ou le sélectionne puis appuie sur la barre d'espace, il s'ouvre par « torsion », révélant son contenu. L'utilisation courante d'un triangle qui pivote ou se tord pour représenter l'ouverture ou la fermeture du composant explique pourquoi on les appelle parfois « twisty » en anglais.

Vous pouvez utiliser du CSS pour mettre en forme le composant de divulgation, et vous pouvez l'ouvrir ou le fermer de façon programmatique en définissant ou en supprimant son attribut open. Malheureusement, il n'existe actuellement aucun moyen intégré d'animer la transition entre l'ouverture et la fermeture.

Par défaut, lorsqu'il est fermé, le composant n'est assez haut que pour afficher le triangle de divulgation et le résumé. Lorsqu'il est ouvert, il s'étend pour afficher les détails qu'il contient.

Les implémentations entièrement conformes aux normes appliquent automatiquement le CSS display: list-item à l'élément <summary>. Vous pouvez utiliser cela ou le pseudo-élément ::marker pour personnaliser le composant de divulgation.

Attributs

Cet élément inclut uniquement les attributs universels.

open

Cet attribut booléen indique si les détails — c'est-à-dire le contenu de l'élément <details> — sont actuellement visibles ou non. Les détails sont affichés lorsque cet attribut existe, ou cachés lorsque cet attribut est absent. Par défaut, cet attribut est absent, ce qui signifie que les détails ne sont pas visibles.

Note : Vous devez supprimer entièrement cet attribut pour que les détails soient cachés. Attention, open="false" rend les détails visibles, car cet attribut est booléen.

name

Cet attribut permet de relier plusieurs éléments <details> pour qu'un seul soit ouvert à la fois. Cela permet aux développeur·euse·s de créer facilement des composants d'interface comme des accordéons sans script.

L'attribut name définit un nom de groupe — donnez la même valeur name à plusieurs éléments <details> pour les regrouper. Un seul des éléments <details> du groupe peut être ouvert à la fois — ouvrir l'un fermera l'autre. Si plusieurs éléments <details> du groupe ont l'attribut open, seul le premier dans l'ordre du code source sera affiché ouvert.

Note : Les éléments <details> n'ont pas besoin d'être adjacents dans le code source pour faire partie du même groupe.

Évènements

En plus des évènements classiques pris en charge par les éléments HTML, l'élément <details> prend en charge l'évènement toggle, qui est envoyé à l'élément <details> chaque fois que son état change entre ouvert et fermé. Il est envoyé après que l'état a changé, mais si l'état change plusieurs fois avant que le navigateur puisse envoyer l'évènement, les évènements sont regroupés et un seul est envoyé.

Vous pouvez utiliser un écouteur d'évènement pour toggle afin de détecter quand le composant change d'état :

details.addEventListener(
  "toggle",
  (event) => {
    if (details.open) {
      /* l'état est passé en "ouvert" */
    } else {
      /* l'état est passé en "fermé" */
    }
  },
  false,
);

Exemples

Un exemple simple de divulgation

Cet exemple montre un élément <details> de base avec un <summary>.

<details>
  <summary>Configuration requise</summary>
  <p>
    Nécessite un ordinateur équipé d'un système d'exploitation. L'ordinateur
    doit disposer d'une mémoire et, idéalement, d'un stockage à long terme. Un
    dispositif d'entrée ainsi qu'un dispositif de sortie sont recommandés.
  </p>
</details>

Résultat

Créer une boîte de divulgation ouverte

Pour obtenir une boîte <details> dans un état ouvert, ajoutez l'attribut booléen open :

<details open>
  <summary>Configuration requise</summary>
  <p>
    Nécessite un ordinateur équipé d'un système d'exploitation. L'ordinateur
    doit disposer d'une mémoire et, idéalement, d'un stockage à long terme. Un
    dispositif d'entrée ainsi qu'un dispositif de sortie sont recommandés.
  </p>
</details>

Résultat

Plusieurs boîtes de divulgation nommées

Voici plusieurs boîtes <details>, toutes avec le même nom pour qu'une seule puisse être ouverte à la fois :

<details name="requirements">
  <summary>Conditions d'obtention du diplôme</summary>
  <p>
    Nécessite 40 crédits, dont une note suffisante en santé, géographie,
    histoire, économie et menuiserie.
  </p>
</details>
<details name="requirements">
  <summary>Configuration requise</summary>
  <p>
    Nécessite un ordinateur équipé d'un système d'exploitation. L'ordinateur
    doit disposer d'une mémoire et, idéalement, d'un stockage à long terme. Un
    dispositif d'entrée ainsi qu'un dispositif de sortie sont recommandés.
  </p>
</details>
<details name="requirements">
  <summary>Exigences pour le poste</summary>
  <p>
    Nécessite des connaissances en HTML, CSS, JavaScript, accessibilité,
    performance web, confidentialité, sécurité, internationalisation, ainsi
    qu'une aversion pour le brocoli.
  </p>
</details>

Résultat

Essayez d'ouvrir tous les widgets de divulgation. Lorsque vous en ouvrez un, tous les autres se ferment automatiquement.

Personnaliser l'apparence

Appliquons maintenant un peu de CSS pour personnaliser l'apparence de la boîte de divulgation.

CSS

details {
  font:
    16px "Open Sans",
    "Calibri",
    sans-serif;
  width: 620px;
}

details > summary {
  padding: 2px 6px;
  width: 15em;
  background-color: #dddddd;
  border: none;
  box-shadow: 3px 3px 4px black;
  cursor: pointer;
}

details > p {
  border-radius: 0 0 10px 10px;
  background-color: #dddddd;
  padding: 2px 6px;
  margin: 0;
  box-shadow: 3px 3px 4px black;
}

details:open > summary {
  background-color: #ccccff;
}

Ce CSS crée une apparence similaire à une interface à onglets, où cliquer sur l'onglet l'ouvre pour révéler son contenu.

HTML

<details>
  <summary>Configuration requise</summary>
  <p>
    Nécessite un ordinateur équipé d'un système d'exploitation. L'ordinateur
    doit disposer d'une mémoire et, idéalement, d'un stockage à long terme. Un
    dispositif d'entrée ainsi qu'un dispositif de sortie sont recommandés.
  </p>
</details>

Résultat

Voir la page <summary> pour un exemple de personnalisation du widget de divulgation.

Résumé technique

Spécifications

Compatibilité des navigateurs

Voir aussi

• L'élément <summary>
• Le pseudo-élément CSS ::details-content