HTMLElement.togglePopover() — Methode · JavaScript-Referenz

Signatur

HTMLElement.prototype.togglePopover(force | options)

Beschreibung

togglePopover() gehört zur Popover-API. Die Methode wechselt den Zustand eines Elements mit popover-Attribut: Ist das Popover geschlossen, wird es geöffnet (wie mit showPopover()). Ist es offen, wird es geschlossen (wie mit hidePopover()). Das Popover erscheint in der Top Layer über allen anderen Inhalten, ohne dass Sie sich um z-index kümmern müssen.

Sie brauchen die Methode, wenn ein Popover aus JavaScript gesteuert werden soll und nicht nur deklarativ über popovertarget an einem Button. Typische Fälle sind Tastenkürzel, eigene Steuerelemente oder Popovers, die nach einer Prüfung oder einem Netzwerkaufruf eingeblendet werden.

Das optionale Argument force verhält sich wie bei DOMTokenList.toggle(): true öffnet immer, false schließt immer. Ist das Popover schon im gewünschten Zustand, passiert nichts und es wird kein Fehler ausgelöst. In neueren Browsern können Sie stattdessen ein Objekt { force, source } übergeben. source legt das auslösende Element fest. Das wirkt sich auf die Barrierefreiheit und das Anker-Verhalten aus.

Beim Umschalten werden die Events beforetoggle (abbrechbar, wenn geöffnet wird) und toggle ausgelöst. Den aktuellen Zustand können Sie auch über die CSS-Pseudoklasse :popover-open abfragen, zum Beispiel mit el.matches(":popover-open").

Parameter

Name	Typ	Default	Beschreibung
$force	boolean		`true` öffnet das Popover immer, `false` schließt es immer. Ohne Angabe wird umgeschaltet.
$options	{ force?: boolean, source?: HTMLElement }		Alternative Objekt-Form (neuere Browser). `force` wirkt wie oben. `source` ist das auslösende Element, das für die Beziehung in der Barrierefreiheit und für die implizite Ankerpositionierung genutzt wird.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Popover nach dem Aufruf geöffnet ist, sonst false. Ältere Implementierungen geben undefined zurück.

Beispiele

Popover per Tastenkürzel umschalten

// HTML: <div id="hilfe" popover>Tastenkürzel: ? = Hilfe, Esc = schließen</div>
const hilfe = document.getElementById("hilfe");

document.addEventListener("keydown", (event) => {
  if (event.key === "?" && !event.repeat) {
    const offen = hilfe.togglePopover();
    console.log(`Hilfe ist jetzt ${offen ? "offen" : "geschlossen"}`);
  }
});

Hilfe ist jetzt offen Hilfe ist jetzt geschlossen

Zustand erzwingen mit force

// HTML: <div id="status" popover="manual">Verbindung verloren</div>
const status = document.getElementById("status");

const aktualisiereStatus = () => {
  // offline → anzeigen, online → ausblenden; keine Fehler bei doppeltem Aufruf
  status.togglePopover(!navigator.onLine);
};

window.addEventListener("online", aktualisiereStatus);
window.addEventListener("offline", aktualisiereStatus);
aktualisiereStatus();

Mit Fallback und Feature-Erkennung

const menue = document.querySelector("#menue");
const button = document.querySelector("#menue-button");

const unterstuetzt = typeof HTMLElement.prototype.togglePopover === "function";

button.addEventListener("click", () => {
  if (!unterstuetzt) {
    menue.hidden = !menue.hidden; // einfacher Fallback
    return;
  }
  try {
    // Objekt-Form mit source; ältere Browser ignorieren das Objekt als truthy force
    menue.togglePopover({ source: button });
  } catch (err) {
    console.error("Popover konnte nicht umgeschaltet werden:", err.name);
  }
});

menue.addEventListener("toggle", (e) => {
  console.log(`${e.oldState} → ${e.newState}`);
  button.setAttribute("aria-expanded", String(e.newState === "open"));
});

closed → open

// Wichtig · Fallstricke

Ausnahmen: Hat das Element kein gültiges popover-Attribut, wird ein NotSupportedError (DOMException) ausgelöst. Ein InvalidStateError kommt, wenn das Element nicht im Dokument hängt, ein modal geöffnetes <dialog> ist oder sich im Vollbildmodus befindet.
Objekt-Form: { force, source } gibt es erst ab Chrome/Edge 133. Ältere Browser werten ein Objekt als truthy force und öffnen das Popover dann nur noch, statt umzuschalten. Wenn es Ihnen nur ums Umschalten geht, rufen Sie die Methode ohne Argument auf.
Rückgabewert: Frühe Implementierungen (z. B. Chrome 114–123) geben undefined zurück. Für einen zuverlässigen Zustand nutzen Sie el.matches(":popover-open").
Ein preventDefault() im beforetoggle-Event verhindert nur das Öffnen, nicht das Schließen.
Popovers mit popover="auto" schließen andere offene auto-Popovers und lassen sich per Esc oder Klick außerhalb schließen (Light Dismiss). Bei popover="manual" passiert beides nicht.
Browser-Unterstützung: Baseline seit April 2024. Für ältere Browser gibt es ein Polyfill (@oddbird/popover-polyfill).

Siehe auch

HTMLElement.hidePopover() HTMLElement.showPopover() HTMLElement.blur() HTMLElement.click() HTMLElement.focus()