API Popover
===========

Limited availability
--------------------

This feature is not Baseline because it does not work in some of the most widely-used browsers.

* Learn more
* See full compatibility
* Report feedback
L'**API Popover** offre aux développeuses et développeurs un mécanisme standard, flexible et cohérent pour afficher des contenus sous forme de *popover* par-dessus les autres contenus d'une page. L'affichage des contenus en *popovers* peut être contrôlé de manière déclarative en utilisant des attributs HTML, ou via JavaScript.

Concepts et utilisation
-----------------------

Un schéma très courant sur le Web consiste à afficher des contenus par-dessus d'autres, attirant l'attention de la personne sur des informations importantes ou des actions à réaliser. Ces contenus peuvent prendre plusieurs noms : superpositions, *popups*, *popovers*, boîtes de dialogue, etc. Nous les appellerons *popovers* dans cette documentation. En règle générale, ils peuvent être :

Modaux

Ce qui signifie que, lorsqu'un *popover* est affiché, le reste de la page est rendu non interactif jusqu'à ce qu'on interagisse avec le *popovers* d'une manière ou d'une autre (par exemple pour effectuer un choix important).

Non-modaux

Ce qui signifie que le reste de la page reste interactif pendant que le *popover* est affiché.

Les *popovers* créés à l'aide de l'API Popover sont toujours non-modaux. Si vous souhaitez créer un *popover* modal, l'élément `<dialog>` est la bonne solution. Cependant, gardez à l'esprit que les éléments `<dialog>` ne sont pas placés dans la couche supérieure (en-US) par défaut, contrairement aux *popovers*. Il y a un recoupement important entre les deux : il est tout à fait possible de créer un *popover* persistant, et de le contrôler en utilisant du HTML déclaratif. Vous pouvez même transformer un élément `<dialog>` en *popover* si vous souhaitez combiner le contrôle des *popovers* et le placement en surimpression avec la sémantique des boîtes de dialogue.

Les cas d'utilisation typiques de l'API Popover incluent les éléments d'interfaces utilisateur interactifs comme les menus d'action, les notifications personnalisées de type *toast*, les suggestions d'éléments de formulaire, les sélecteurs de contenu ou les interfaces d'apprentissage.

Vous pouvez créer des popovers de deux manières différentes :

* De manière déclarative, via un ensemble de nouveaux attributs HTML. Un *popover* simple avec un bouton d'activation peut être créé en utilisant le code suivant :

```html
<button popovertarget="mypopover">Basculer le popover</button>
<div id="mypopover" popover>Contenu du popover</div>
```

* Via une API JavaScript. Par exemple, la méthode `HTMLElement.togglePopover()` peut être utilisée pour basculer un *popover* entre les états affiché et masqué.

Il existe également de nouveaux évènements pour réagir à l'activation d'un *popover*, ainsi que des fonctionnalités CSS pour faciliter la mise en forme des *popovers*. Toutes les fonctionnalités associées sont répertoriées ci-après.

Voir Utiliser l'API Popover pour un guide détaillé sur l'utilisation de cette API.

Attributs HTML
--------------

`popover`

Un attribut universel qui transforme un élément en élément *popover* et qui prend un état de *popover* (`"auto"` ou `"manual"`) comme valeur.

`popovertarget`

Transforme un élément `<button>` ou `<input>` en bouton de contrôle de *popover*. La valeur de cet attribut correspond à l'identifiant de l'élément *popover* à contrôler.

`popovertargetaction`

Spécifie l'action à effectuer (`"hide"`, `"show"` ou `"toggle"`) sur l'élément *popover* contrôlé par un élément de contrôle `<button>` ou `<input>`.

Fonctionnalités CSS
-------------------

`::backdrop`

Le pseudo-élément `::backdrop` est un élément plein écran placé directement derrière les éléments *popovers*, permettant d'ajouter des effets au contenu de la page derrière les *popovers* si nécessaire (par exemple en le floutant).

`:popover-open`

La pseudo-classe `:popover-open` correspond à un élément *popover* uniquement lorsqu'il est affiché. Elle peut être utilisée pour styliser les éléments *popovers* lorsqu'ils sont affichés.

Interfaces
----------

`ToggleEvent`

Représente un évènement de notification lorsqu'un élément *popover* bascule entre les états affiché et masqué. Elle est implémentée par les évènements `beforetoggle` et `toggle`, qui se déclenchent sur les *popovers* lorsque leur état change.

Extensions aux autres interfaces
--------------------------------

### Propriétés d'instance

`HTMLElement.popover`

Permet de connaître ou de modifier l'état de l'élément *popover* via JavaScript (`"auto"` ou `"manual"`). Elle peut être utilisée pour détecter la prise en charge des fonctionnalités *popover*. Cette propriété reflète l'attribut HTML `popover`.

`HTMLButtonElement.popoverTargetElement` et `HTMLInputElement.popoverTargetElement`

Permet de connaître ou de modifier l'élément *popover* contrôlé par le bouton. C'est l'équivalent JavaScript de l'attribut HTML `popovertarget`.

`HTMLButtonElement.popoverTargetAction` et `HTMLInputElement.popoverTargetAction`

Permet de connaître ou de modifier l'action à effectuer (`"hide"`, `"show"` ou `"toggle"`) sur l'élément *popover* contrôlé par le bouton. Cette propriété reflète la valeur de l'attribut HTML `popovertargetaction`.

### Méthodes d'instance

`HTMLElement.hidePopover()`

Masque l'élément *popover* en le supprimant de la couche supérieure et en le masquant avec `display: none`.

`HTMLElement.showPopover()`

Affiche l'élément *popover* en le plaçant dans la couche supérieure.

`HTMLElement.togglePopover()`

Bascule l'élément *popover* entre les états affiché et masqué.

### Évènements

Évènement `beforetoggle`, rattaché à `HTMLElement`

Déclenché juste avant que l'état d'un élément *popover* ne change entre affiché et masqué, ou vice versa.

Évènement `toggle`, rattaché à `HTMLElement`

Déclenché lorsque l'état d'un élément *popover* a changé entre les états affiché et masqué, ou vice versa. Voir l'évènement analogue `toggle` de `HTMLDetailsElement` (en-US) qui signale les changements d'états des éléments `<details>`.

Exemples
--------

Voir notre page d'exemples de l'API Popover pour accéder à l'ensemble des exemples MDN sur ce sujet.

Spécifications
--------------

| Specification |
| --- |
| HTML Standard # dom-popover |

Compatibilité des navigateurs
-----------------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.