Element: beforematch — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("beforematch", handler)

Beschreibung

Das Event beforematch gehört zum Zustand versteckt bis gefunden. Diesen Zustand erreicht ein Element über das Attribut hidden="until-found" (bzw. element.hidden = "until-found"). Der Inhalt wird dann per content-visibility: hidden ausgeblendet, bleibt aber für die „Auf Seite suchen“-Funktion des Browsers (Strg+F), für Text-Fragmente (#:~:text=…) und für normale Fragment-Links (#id) durchsuchbar.

Findet der Browser einen Treffer in einem solchen Element, feuert er zuerst beforematch auf dem versteckten Element, entfernt danach das hidden-Attribut und scrollt zum Treffer. Im Handler kannst du also den restlichen Oberflächenzustand anpassen, bevor der Inhalt sichtbar wird, etwa einen Akkordeon-Button auf „geöffnet“ stellen, aria-expanded aktualisieren oder den geöffneten Abschnitt in der URL oder im Speicher festhalten.

Einen Handler meldest du mit addEventListener("beforematch", …) oder über die Eigenschaft onbeforematch an. Das Event ist ein normales Event ohne zusätzliche Eigenschaften, es steigt auf (bubbles: true) und lässt sich nicht abbrechen. preventDefault() verhindert das Aufdecken also nicht.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Eventname `"beforematch"`.
$handler Pflicht	(event: Event) => void		Callback, das vor dem Aufdecken des Elements aufgerufen wird. `event.target` ist das Element mit `hidden="until-found"`.
$options	boolean \| AddEventListenerOptions	false	Übliche Optionen wie `once`, `capture` oder `signal`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Das Event ist ein einfaches Event-Objekt.

Beispiele

Akkordeon, das sich bei Seitensuche automatisch öffnet

// HTML:
// <button aria-expanded="false" aria-controls="faq1">Versand</button>
// <div id="faq1" hidden="until-found">Wir versenden innerhalb von 24 Stunden.</div>

const button = document.querySelector('[aria-controls="faq1"]');
const panel = document.getElementById('faq1');

const setOpen = (open) => {
  button.setAttribute('aria-expanded', String(open));
  if (open) {
    panel.removeAttribute('hidden');
  } else {
    panel.hidden = 'until-found';
  }
};

button.addEventListener('click', () => {
  setOpen(button.getAttribute('aria-expanded') !== 'true');
});

// Strg+F findet "24 Stunden": Button-Zustand vor dem Aufdecken anpassen
panel.addEventListener('beforematch', () => {
  console.log('Panel wird durch die Suche geöffnet');
  button.setAttribute('aria-expanded', 'true');
});

Panel wird durch die Suche geöffnet

Handler über onbeforematch und Delegation für mehrere Abschnitte

// Alle versteckten Abschnitte eines Containers behandeln (das Event steigt auf)
const container = document.querySelector('#doku');

container.addEventListener('beforematch', (event) => {
  const section = event.target;
  section.classList.add('open');
  console.log(`Aufgedeckt: #${section.id}`);
});

// Alternativ direkt per Eigenschaft an einem Element
const intro = document.querySelector('#intro');
intro.onbeforematch = () => console.log('Intro wird gleich sichtbar');

Aufgedeckt: #kapitel-3

Funktionserkennung mit Rückfallebene

const panels = document.querySelectorAll('.panel');
const supportsUntilFound = 'onbeforematch' in document.body;

panels.forEach((panel) => {
  if (supportsUntilFound) {
    panel.hidden = 'until-found';
    panel.addEventListener('beforematch', () => {
      panel.dataset.state = 'open';
    }, { once: true });
  } else {
    // Ohne Unterstützung sichtbar lassen, damit die Suche weiterhin funktioniert
    panel.hidden = false;
  }
});

console.log(supportsUntilFound);

true (in Chromium-Browsern)

// Wichtig · Fallstricke

Nicht abbrechbar: preventDefault() hat keine Wirkung. Der Browser entfernt das hidden-Attribut nach dem Event in jedem Fall.
Nur bei hidden="until-found": Bei einfachem hidden oder display: none wird der Inhalt nicht durchsucht, und das Event feuert nicht. Setzt dein eigenes CSS display: none auf das Element, geht der Mechanismus ebenfalls kaputt.
Das Event wird ausgelöst, bevor das Attribut entfernt wird. Im Handler gilt also noch element.hidden === "until-found". Entfernst du das Attribut im Handler selbst, schadet das nicht.
Auch das <details>-Element öffnet sich in Chromium bei Seitensuche automatisch. Dort ist aber das Event toggle maßgeblich, nicht beforematch.
Kompatibilität: Chromium ab Version 102, Firefox ab Version 139. Safari unterstützt es noch nicht (Stand 2025). Prüfe die Unterstützung mit 'onbeforematch' in document.body. Ohne Unterstützung wird hidden="until-found" wie normales hidden behandelt, der Inhalt bleibt dann unauffindbar. Sieh dafür eine Rückfallebene vor.
Barrierefreiheit: Halte aria-expanded an steuernden Buttons im Handler synchron.

Siehe auch

Event Element CreateMonitor: downloadprogress Element: beforexrselect Element: beforeinput