HTMLElement.showPopover() — Methode · JavaScript-Referenz

Signatur

HTMLElement.prototype.showPopover(options)

Beschreibung

showPopover() öffnet ein Element, das mit dem globalen HTML-Attribut popover als Popover markiert ist. Das Element wird in den Top Layer gelegt. Dadurch erscheint es über allen anderen Inhalten, und zwar unabhängig von z-index, overflow: hidden oder dem Stapelkontext der Eltern-Elemente. Das entspricht dem Verhalten eines Buttons mit popovertarget, nur dass du es per Skript auslöst.

Wie sich das Popover verhält, hängt vom Wert des Attributs ab:

popover bzw. popover="auto": Das Popover schließt sich von selbst (Light Dismiss), wenn man außerhalb klickt oder Esc drückt. Andere offene auto-Popover, die nicht seine Vorfahren sind, werden dabei geschlossen.
popover="manual": Das Popover bleibt offen, bis es ausdrücklich geschlossen wird, etwa mit hidePopover() oder togglePopover(). Das eignet sich für Toasts und Benachrichtigungen.
popover="hint" (neuer, noch nicht überall unterstützt): für Tooltips. Solche Popover schließen keine offenen auto-Popover.

Vor dem Öffnen wird das abbrechbare Ereignis beforetoggle ausgelöst (newState: "open"), danach asynchron das Ereignis toggle. Über die Option source gibst du ein auslösendes Element an. Dann funktionieren Tastatur-Fokus-Navigation, Barrierefreiheits-Beziehungen und die implizite CSS-Anchor-Positionierung genauso wie bei popovertarget.

Parameter

Name	Typ	Default	Beschreibung
$options	object		Optionales Konfigurationsobjekt. Es wird nur in neueren Browsern unterstützt (z. B. ab Chrome 133).
$options.source	HTMLElement		Das Element, das das Popover auslöst (meist ein Button). Es stellt eine implizite Anker- und Barrierefreiheits-Beziehung her, wie `popovertarget`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Popover per Skript öffnen

// HTML: <div id="info" popover>Gespeichert!</div>
//       <button id="save">Speichern</button>
const info = document.getElementById('info');

document.getElementById('save').addEventListener('click', () => {
  info.showPopover();
  console.log(info.matches(':popover-open'));
});

true

Toast mit popover="manual", der sich selbst schließt

// HTML: <div id="toast" popover="manual"></div>
const toast = document.getElementById('toast');

const notify = (message, ms = 3000) => {
  toast.textContent = message;
  if (!toast.matches(':popover-open')) {
    toast.showPopover();
  }
  clearTimeout(notify.timer);
  notify.timer = setTimeout(() => toast.hidePopover(), ms);
};

notify('Datei erfolgreich hochgeladen');

Auf beforetoggle/toggle reagieren und Öffnen verhindern

// HTML: <div id="menu" popover>…</div>
const menu = document.getElementById('menu');
let locked = false;

menu.addEventListener('beforetoggle', (event) => {
  if (event.newState === 'open' && locked) {
    event.preventDefault(); // Öffnen abbrechen
  }
});

menu.addEventListener('toggle', (event) => {
  console.log(`Popover ist jetzt: ${event.newState}`);
});

menu.showPopover();

Popover ist jetzt: open

Mit source-Option und Feature-Erkennung

// HTML: <button id="trigger">Hilfe</button>
//       <div id="help" popover>Kurze Hilfe…</div>
const trigger = document.getElementById('trigger');
const help = document.getElementById('help');

const supportsPopover = HTMLElement.prototype.hasOwnProperty('popover');

trigger.addEventListener('click', () => {
  if (!supportsPopover) {
    help.hidden = false; // einfacher Rückfall
    return;
  }
  try {
    // Ältere Browser ignorieren das Options-Objekt einfach
    help.showPopover({ source: trigger });
  } catch (err) {
    console.error(err.name, err.message);
  }
});

// Wichtig · Fallstricke

Ausnahmen: Hat das Element kein popover-Attribut, wird eine NotSupportedError-DOMException geworfen. Eine InvalidStateError entsteht, wenn das Element nicht im Dokument hängt oder ein modal geöffnetes <dialog> ist.
Bereits geöffnet: Nach der aktuellen Spezifikation passiert beim erneuten Aufruf auf einem offenen Popover nichts. Frühe Implementierungen haben dagegen eine InvalidStateError geworfen. Prüfe deshalb vorher mit el.matches(':popover-open'), ob das Popover schon offen ist.
Wenn beforetoggle mit preventDefault() abgebrochen wird, bleibt das Popover geschlossen, und zwar ohne Fehlermeldung.
Das Öffnen eines auto-Popovers schließt andere offene auto-Popover, die nicht seine Vorfahren sind. Bei verschachtelten Menüs kommt es deshalb auf die DOM-Struktur bzw. die source-Beziehung an.
Positionierung: Standardmäßig wird ein Popover per UA-Stylesheet mittig im Viewport angezeigt. Für eine Ausrichtung am Auslöser brauchst du CSS Anchor Positioning (noch nicht überall verfügbar) oder eigenes JavaScript.
Kompatibilität: Baseline seit April 2024 (Chrome/Edge 114, Safari 17, Firefox 125). Die Option source und popover="hint" sind neuer und noch nicht in allen Browsern verfügbar. Für ältere Browser gibt es ein Polyfill (@oddbird/popover-polyfill).

Siehe auch

HTMLElement.hidePopover() HTMLElement.togglePopover() HTMLElement.popover HTMLDialogElement.showModal() ToggleEvent