HTMLButtonElement.popoverTargetElement — Eigenschaft · JavaScript-Referenz

Signatur

HTMLButtonElement.popoverTargetElement

Beschreibung

Mit popoverTargetElement verknüpfen Sie einen Button per JavaScript mit einem Popover-Element, also einem Element mit dem Attribut popover. Die Eigenschaft entspricht dem HTML-Attribut popovertarget. Sie erwartet aber keine ID-Zeichenkette, sondern direkt eine Elementreferenz. Klickt der Nutzer auf den Button, öffnet, schließt oder schaltet der Browser das Popover um, und zwar ohne eigenen Event-Handler. Welche Aktion ausgeführt wird, bestimmt popoverTargetAction.

Die Eigenschaft ist vor allem bei dynamisch erzeugten Oberflächen nützlich: Das Ziel-Element hat dort oft keine ID, liegt in einem anderen Baum oder wird erst zur Laufzeit gebaut. Beim Lesen erhalten Sie das aktuell verknüpfte Element oder null. Wurde das Attribut popovertarget im HTML gesetzt, liefert der Getter das Element mit der passenden ID.

Die Verknüpfung per Deklaration hat mehrere Vorteile. Der Browser setzt die Barrierefreiheits-Beziehungen automatisch, zum Beispiel aria-expanded und die Verbindung zwischen Auslöser und Popover. Er gibt den Fokus beim Schließen an den Button zurück. Außerdem verankert er das Popover für CSS Anchor Positioning implizit am Button. All das müssten Sie bei einer reinen Lösung mit click-Handler und showPopover() selbst umsetzen.

Parameter

Name	Typ	Default	Beschreibung
$value	Element \| null	null	Beim Setzen: das Element mit dem Attribut `popover`, das gesteuert werden soll. Mit `null` heben Sie die Verknüpfung auf.

Rückgabewert

Typ

Element | null

Beschreibung

Das verknüpfte Popover-Element oder null, wenn kein Ziel gesetzt ist.

Beispiele

Popover per JavaScript mit einem Button verknüpfen

// HTML: <button id="toggle">Menü</button>
//       <div id="menu" popover>Menüinhalt</div>
const button = document.getElementById('toggle');
const menu = document.getElementById('menu');

button.popoverTargetElement = menu;
button.popoverTargetAction = 'toggle'; // Standardwert

console.log(button.popoverTargetElement === menu);

true

Dynamisch erzeugtes Popover ohne ID steuern

const tip = document.createElement('div');
tip.popover = 'auto';
tip.textContent = 'Hilfetext zu diesem Feld';
document.body.append(tip);

const helpBtn = document.createElement('button');
helpBtn.textContent = '?';
helpBtn.popoverTargetElement = tip; // keine ID nötig
document.body.append(helpBtn);

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

Popover ist jetzt: open (nach Klick auf den Button)

Aus HTML-Attribut lesen und Verknüpfung entfernen

// HTML: <button id="b" popovertarget="dlg">Info</button>
//       <div id="dlg" popover>Details</div>
const b = document.getElementById('b');
console.log(b.popoverTargetElement?.id);

// Verknüpfung aufheben – der Button tut beim Klick nichts mehr
b.popoverTargetElement = null;
console.log(b.popoverTargetElement);

dlg null

Separate Buttons zum Öffnen und Schließen

const panel = document.querySelector('#panel'); // <div id="panel" popover="manual">
const openBtn = document.querySelector('#open');
const closeBtn = document.querySelector('#close');

openBtn.popoverTargetElement = panel;
openBtn.popoverTargetAction = 'show';

closeBtn.popoverTargetElement = panel;
closeBtn.popoverTargetAction = 'hide';

// Wichtig · Fallstricke

Nur bei gültigem Ziel wirksam: Hat das Ziel-Element kein Attribut popover, passiert beim Klick nichts. Einen Fehler gibt es nicht.
Button-Typ beachten: Die Verknüpfung greift nur, wenn der Button nicht als Absende- oder Zurücksetzen-Button in einem Formular wirkt, also nicht als type="submit" bzw. type="reset" in einem <form>. In Formularen sollten Sie deshalb type="button" setzen. Deaktivierte Buttons (disabled) lösen ebenfalls nichts aus.
Attribut und Eigenschaft: Das Setzen der Eigenschaft ändert das Attribut popovertarget nicht. Die Referenz wird intern gespeichert, und getAttribute('popovertarget') spiegelt sie nicht wider.
Shadow DOM: Sie können Elemente außerhalb des eigenen Shadow Roots zuweisen, aber nur, wenn das Ziel im selben oder in einem übergeordneten Baum liegt. Andernfalls liefert der Getter null.
Kompatibilität: Seit 2024 in allen aktuellen Browsern verfügbar (Baseline). Für ältere Browser prüfen Sie die Unterstützung mit 'popoverTargetElement' in HTMLButtonElement.prototype und binden bei Bedarf ein Polyfill ein, zum Beispiel @oddbird/popover-polyfill.
Dieselbe Eigenschaft gibt es auch an HTMLInputElement, etwa bei <input type="button">.

Siehe auch

HTMLButtonElement.formNoValidate HTMLButtonElement.popoverTargetAction HTMLButtonElement.commandForElement HTMLButtonElement.interestForElement HTMLButtonElement.formTarget