HTMLElement.popover — Eigenschaft · JavaScript-Referenz

Signatur

HTMLElement.popover

Beschreibung

Die Eigenschaft popover ist die JavaScript-Entsprechung des globalen HTML-Attributs popover. Sie spiegelt das Attribut: Wenn du die Eigenschaft liest, erhältst du den normalisierten Wert des Attributs. Wenn du sie setzt, wird das Attribut geändert. Ein Element mit gesetztem popover ist zunächst verborgen und lässt sich über showPopover(), hidePopover(), togglePopover() oder deklarativ über popovertarget ein- und ausblenden. Sichtbare Popover liegen im Top Layer, also über allen anderen Inhalten.

Die möglichen Zustände:

"auto": Das Popover wird durch „Light Dismiss“ geschlossen, also durch einen Klick außerhalb oder die Esc-Taste. Wird ein weiteres auto-Popover geöffnet, das nicht verschachtelt ist, schließen sich die anderen. Diesen Wert liefert auch ein leeres Attribut (<div popover>).
"hint": Gedacht für Tooltips. Das Popover schließt keine offenen auto-Popover, wohl aber andere hint-Popover. Light Dismiss funktioniert auch hier.
"manual": Es gibt kein Light Dismiss und kein automatisches Schließen anderer Popover. Das Element muss ausdrücklich geschlossen werden. Diesen Wert liefert auch jeder ungültige Attributwert.
null: Das Attribut fehlt, das Element ist also kein Popover.

In der Praxis nutzt du die Eigenschaft, um Elemente zur Laufzeit zu Popovers zu machen, zum Beispiel bei dynamisch erzeugten Menüs, Toasts oder Tooltips. Du kannst damit auch das Verhalten wechseln (auto ↔ manual) oder die Unterstützung der API erkennen (Feature-Detection).

Parameter

Name	Typ	Default	Beschreibung
$value (Setter)	string \| null		Neuer Popover-Zustand: `"auto"`, `"hint"` oder `"manual"`. Mit `null` wird das Attribut `popover` entfernt. Andere Zeichenketten werden als Attributwert übernommen und beim Lesen als `"manual"` ausgewertet.

Rückgabewert

Typ

"auto" | "hint" | "manual" | null

Beschreibung

Der normalisierte Popover-Zustand. Ein leeres Attribut ergibt "auto", ein ungültiger Wert "manual" und ein fehlendes Attribut null.

Beispiele

Zustand auslesen und Normalisierung verstehen

// HTML:
// <div id="a" popover>Menü</div>
// <div id="b" popover="manual">Toast</div>
// <div id="c" popover="quatsch">?</div>
// <div id="d">Kein Popover</div>

for (const id of ['a', 'b', 'c', 'd']) {
  const el = document.getElementById(id);
  console.log(id, el.popover);
}

a auto b manual c manual d null

Dynamisch erzeugten Toast als manuelles Popover anzeigen

const showToast = (text, dauer = 3000) => {
  const toast = document.createElement('div');
  toast.className = 'toast';
  toast.textContent = text;
  toast.popover = 'manual'; // kein Light Dismiss
  document.body.append(toast);
  toast.showPopover();

  setTimeout(() => {
    toast.hidePopover();
    toast.remove();
  }, dauer);
};

showToast('Änderungen gespeichert');

Feature-Detection mit Fallback

const supportsPopover = Object.hasOwn(HTMLElement.prototype, 'popover');

const dialog = document.querySelector('#hilfe');

if (supportsPopover) {
  dialog.popover = 'auto';
  document.querySelector('#hilfe-btn')
    .addEventListener('click', () => dialog.togglePopover());
} else {
  // Fallback: einfaches Ein-/Ausblenden
  dialog.hidden = true;
  document.querySelector('#hilfe-btn')
    .addEventListener('click', () => { dialog.hidden = !dialog.hidden; });
}

console.log('Popover-API verfügbar:', supportsPopover);

Popover-API verfügbar: true

Popover-Eigenschaft wieder entfernen

const panel = document.querySelector('#panel');
panel.popover = 'auto';
console.log(panel.getAttribute('popover')); // "auto"

panel.popover = null; // Attribut wird entfernt
console.log(panel.hasAttribute('popover'), panel.popover);

auto false null

// Wichtig · Fallstricke

Zustand ändern schließt das Popover: Änderst du popover, während das Element sichtbar ist, wird es sofort verborgen. Danach musst du showPopover() erneut aufrufen.
Ungültige Werte werfen keinen Fehler. Sie führen still zum Zustand "manual". Ein Tippfehler wie "atuo" schaltet also das Light Dismiss unbemerkt ab.
"hint" ist noch nicht überall verfügbar. Der Wert wird nur in Chromium-Browsern ab Version 133 unterstützt. Andere Browser werten ihn als ungültig und damit als "manual". Prüfe das, bevor du dich darauf verlässt, zum Beispiel so: el.popover = 'hint'; el.popover === 'hint'.
showPopover() auf einem Element ohne popover-Attribut wirft eine NotSupportedError-DOMException.
Auf <dialog>-Elementen ist das Attribut erlaubt. Kombiniere es aber nicht mit showModal().
Ältere Browser (vor 2024) kennen die Eigenschaft nicht. Dort ist el.popover undefined, und das Attribut hat keine Wirkung. Nutze Feature-Detection und bei Bedarf ein Polyfill wie @oddbird/popover-polyfill.
Die Positionierung ist bei Popovers standardmäßig zentriert (UA-Stylesheet). Für eine Positionierung am Auslöser brauchst du eigenes CSS oder CSS Anchor Positioning.

Siehe auch

HTMLElement.nonce HTMLElement.dataset HTMLElement.dir HTMLElement.hidden HTMLElement.inert