JavaScript Element beforematch Event

What You’ll Learn

The beforematch event fires on an element in the hidden until found state just before the browser reveals it—when find-in-page or a fragment link matches that content. Learn hidden="until-found", addEventListener vs onbeforematch, the reveal sequence, and five try-it labs.

Introduction

Sometimes you want content to stay collapsed until the user searches for it or jumps to its id. HTML supports that with hidden="until-found". The element is not shown in the page layout, but the browser can still find its text and navigate to it.

Right before the browser removes hidden and scrolls into view, beforematch fires. That is your chance to update text, load data, or log that the section was revealed by search or a deep link.

Understanding beforematch

An instance event that answers: “A find-in-page or fragment match is about to reveal this hidden-until-found element.”

• Requires hidden="until-found" on the element (or an ancestor subtree case the browser scrolls to).
• Triggers from find in page or fragment navigation (#id links).
• Event type — a plain Event (no special fields).
• Order — fire beforematch → remove hidden → scroll.
• Baseline Newly available on MDN (since December 2025).

📝 Syntax

Use the event name with addEventListener, or set the handler property:

addEventListener("beforematch", (event) => { });

onbeforematch = (event) => { };

Event type

A generic Event.

HTML partner attribute

<div id="secret" hidden="until-found">
  Searchable content lives here.
</div>

🔁 The Reveal Sequence

When find-in-page or a fragment link causes a scroll into a hidden-until-found subtree, the browser does this (from MDN):

1. Fire a beforematch event on the hidden element.
2. Remove the hidden attribute from the element.
3. Scroll to the element.

Your handler runs while the element is still conceptually “about to be shown,” so you can prepare UI before users see the final content.

⚖️ Boolean hidden vs until-found

Examples Gallery

Examples follow MDN Element: beforematch event. In try-it labs, click the fragment link (or use find in page) to reveal the box.

const untilFound = document.querySelector("#until-found-box");

untilFound.addEventListener("beforematch", () => {
  untilFound.textContent = "I've been revealed!";
});

I've been revealed!

const box = document.getElementById("until-found-box");

box.onbeforematch = () => {
  console.log("about to reveal:", box.id);
  box.textContent = "Opened via onbeforematch";
};

// Assigning again replaces the previous onbeforematch handler.

about to reveal: until-found-box
Opened via onbeforematch

<a href="#until-found-box">Go to hidden content</a>

<div>I'm not hidden</div>
<div id="until-found-box" hidden="until-found">Hidden until found</div>

<script>
  const box = document.querySelector("#until-found-box");
  box.addEventListener("beforematch", () => {
    box.textContent = "I've been revealed!";
  });
</script>

I've been revealed!

const panel = document.getElementById("faq-panel");
const status = document.getElementById("status");

panel.addEventListener("beforematch", () => {
  panel.classList.add("was-found");
  status.textContent = "Revealed at " + new Date().toLocaleTimeString();
});

Revealed at 8:55:12 PM

function isBeforeMatchAvailable() {
  return "onbeforematch" in document.documentElement;
}

console.log("beforematch available:", isBeforeMatchAvailable());

const box = document.getElementById("until-found-box");
if (isBeforeMatchAvailable()) {
  box.addEventListener("beforematch", () => {
    box.textContent = "Revealed with beforematch support";
  });
} else {
  console.log("Fall back: use a details/summary or expand button");
}

beforematch available: true

🚀 Common Use Cases

• FAQ or docs sections that stay collapsed but remain searchable.
• Updating copy or loading details the moment a deep link opens a panel.
• Analytics when users discover content via find in page.
• Highlighting a section that was revealed by fragment navigation.
• Progressive enhancement on top of hidden="until-found".

🔧 How It Works

📝 Notes

• MDN: Baseline Newly available (since December 2025).
• Not Deprecated, Experimental, or Non-standard — no status banner required.
• Without until-found support, hidden may act as a plain boolean hide.
• Event type is a generic Event—no InputEvent-style fields.
• Related learning: beforeinput, beforescriptexecute, JavaScript hub.

💡 Best Practices