<summary> : l'élément de révélation d'un résumé

Exemple interactif

<details>
  <summary>
    J'ai des clés mais pas de portes. J'ai de l'espace mais pas de pièce. Vous
    pouvez entrer mais ne pouvez pas sortir. Qui suis-je ?
  </summary>
  Un clavier.
</details>

details {
  border: 1px solid #aaa;
  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 #aaa;
  margin-bottom: 0.5em;
}

Attributs

Cet élément inclut uniquement les attributs universels.

Notes d'utilisation

Un élément <summary> peut contenir des éléments de titre, du texte simple ou tout contenu HTML pouvant être placé au sein d'un paragraphe.

Un élément <summary> peut uniquement être utilisé comme le premier élément fils d'un élément <details>. Lorsque l'utilisateur clique sur le résumé, l'élément <details> parent change d'état (affiché ou masqué) et un évènement toggle est envoyé à l'élément <details> (ce qui permet de détecter un changement d'état via un script).

Le contenu de l'élément <details> fournit la description accessible pour l'élément <summary>.

Libellé par défaut

Si le premier enfant d'un élément <details> n'est pas un élément <summary>, l'agent utilisateur utilisera une chaîne de caractères par défaut (généralement « Détails ») comme libellé pour la boîte de révélation.

Mise en forme par défaut

Conformément à la spécification HTML, le style par défaut pour les éléments <summary> inclut display: list-item. Cela permet de changer ou de supprimer l'icône affichée comme widget à côté du libellé, qui est généralement un triangle.

Vous pouvez aussi changer le style en display: block pour supprimer le triangle.

Voir la section Compatibilité des navigateurs pour plus de détails, car tous les navigateurs ne prennent pas encore en charge toutes les fonctionnalités de cet élément.

Pour les navigateurs basés sur WebKit, comme Safari, il est possible de contrôler l'affichage de l'icône via le pseudo-élément CSS non standard ::-webkit-details-marker. Pour supprimer le triangle, utilisez summary::-webkit-details-marker { display: none }.

Exemples

Voici quelques exemples montrant l'utilisation de <summary>. Vous pouvez trouver d'autres exemples dans la documentation de l'élément <details>.

Exemple simple

Un exemple simple montrant l'utilisation de <summary> dans un élément <details> :

HTML

<details open>
  <summary>Détails produit</summary>
  <ol>
    <li>Date de fabrication&nbsp;: 01 janvier 2018</li>
    <li>Numéro de lot&nbsp;: LMA2542501</li>
    <li>Date limite de consommation&nbsp;: 31 août 2018</li>
  </ol>
</details>

Résultat

Utilisation de titres

Il est possible d'utiliser des titres au sein d'un résumé.

HTML

<details open>
  <summary><h4>Détails produit</h4></summary>
  <ol>
    <li>Date de fabrication&nbsp;: 01 janvier 2018</li>
    <li>Numéro de lot&nbsp;: LMA2542501</li>
    <li>Date limite de consommation&nbsp;: 31 août 2018</li>
  </ol>
</details>

Résultat

Il existe actuellement quelques problèmes d'espacement qui peuvent être corrigés à l'aide de CSS.

Utiliser des éléments HTML dans un résumé

Cet exemple ajoute une certaine sémantique à l'élément <summary> pour indiquer que le libellé est important :

HTML

<details open>
  <summary><strong>Détails</strong></summary>
  <ol>
    <li>Date de fabrication&nbsp;: 01 janvier 2018</li>
    <li>Numéro de lot&nbsp;: LMA2542501</li>
    <li>Date limite de consommation&nbsp;: 31 août 2018</li>
  </ol>
</details>

Résultat

Changer l'icône du résumé

Le marqueur de l'élément <summary>, c'est-à-dire le triangle de révélation, peut être personnalisé avec CSS. Le marqueur peut être ciblé à l'aide du pseudo-élément ::marker, qui accepte la propriété abrégée list-style ainsi que ses propriétés détaillées, comme list-style-type. Cela permet de remplacer le triangle par une image (généralement avec list-style-image) ou une chaîne de caractères (y compris des émojis). Dans cet exemple, nous remplaçons le contenu d'un widget de révélation et supprimons l'icône d'un autre en appliquant list-style: none avant d'ajouter une icône personnalisée via du contenu généré.

CSS

Dans le premier widget de révélation, nous mettons en forme le ::marker, en modifiant la propriété content selon l'attribut [open] de l'élément <details>. Pour le second widget, nous supprimons le marqueur avec les propriétés list-style, puis nous ajoutons un contenu généré stylisé avec le pseudo-élément ::after. Nous incluons également des styles pour ::-webkit-details-marker afin de cibler Safari. Le sélecteur pour le pseudo-élément spécifique au navigateur est inclus dans une pseudo-classe :is() afin de ne pas invalider la liste des sélecteurs.

details {
  font-size: 1rem;
  font-family: "Open Sans", Calibri, sans-serif;
  border: solid;
  padding: 2px 6px;
  margin-bottom: 1em;
}

details:first-of-type summary::marker,
:is(::-webkit-details-marker) {
  content: "+ ";
  font-family: monospace;
  color: red;
  font-weight: bold;
}

details[open]:first-of-type summary::marker {
  content: "− ";
}

details:last-of-type summary {
  list-style: none;
  &::after {
    content: "+";
    color: white;
    background-color: darkgreen;
    border-radius: 1em;
    font-weight: bold;
    padding: 0 5px;
    margin-inline-start: 5px;
  }
  [open] &::after {
    content: "−";
  }
}
details:last-of-type summary::-webkit-details-marker {
  display: none;
}

Le CSS inclut le sélecteur d'attribut [open], qui ne correspond que lorsque l'attribut open est présent (c'est-à-dire lorsque l'élément <details> est ouvert). Les pseudo-classes :first-of-type et :last-of-type ciblent respectivement le premier et le dernier élément du même type. Nous avons inclus le pseudo-élément préfixé -webkit- dans une pseudo-classe :is() car elle accepte une liste de sélecteurs tolérante : si le pseudo-élément préfixé est invalide dans un navigateur, tout le bloc de sélecteurs ne sera pas invalidé. Nous avons aussi utilisé la syntaxe imbriquée de CSS. Voir le module Sélecteurs CSS.

HTML

<h1>Citations d'Helen Keller</h1>

<details>
  <summary>Sur les droits des femmes</summary>
  <p>
    <q>Nous avons prié, nous avons supplié, nous avons imploré pour obtenir le droit de vote, dans l'espoir que les hommes, par chevalerie, accorderaient l'égalité des droits aux femmes et les associeraient aux affaires de l'État. Nous espérions que leur bon sens l'emporterait sur les préjugés et la stupidité. Nous pensions que leur sens tant vanté de la justice surmonterait les erreurs qui entravent si souvent l'esprit humain&nbsp;; mais nous sommes toujours reparties les mains vides. Nous ne supplierons plus.</q>
  </p>
</details>

<details>
  <summary>Sur l'optimisme</summary>
  <p>
    <q>L'optimisme est la foi qui mène à la réussite&nbsp;; rien ne peut être accompli sans espoir.</q>
  </p>
</details>

Résultat

Résumé technique

Spécifications

Compatibilité des navigateurs

Voir aussi

• <details>