liveBook · Manning

Event.intercept()

As explained in Vanilla Web

event.intercept() is a navigation-event method that prevents a supported navigation from proceeding natively and assigns application handling to it.

For client-side routing, event.intercept() lets an application handle an eligible navigation without loading a new document. The browser updates the URL and session history; application code renders the view. Use it only for destinations the router can handle, leaving other navigations to the browser. section 10.3.2

A router's interception handler should:

  • Check eligibility and skip hash changes, downloads, external origins, and destinations without a matching route. section 10.3.2
  • Render the matched view in the handler, then update the document title and move focus to a meaningful location. section 10.3.2
  • With scroll: "manual", call event.scroll() after rendering so the browser can apply the navigation's appropriate scroll behavior. section 10.3.2
Listing 10.1 Using the Navigation API to intercept same-document navigations
if ("navigation" in globalThis) {
  navigation.addEventListener("navigate", (event) => {
    if (!event.canIntercept || event.hashChange) return; #1
    if (event.downloadRequest) return; #1

    const url = new URL(event.destination.url);
    if (url.origin !== location.origin) return; #1

    // matchRoute is defined in a separate function.
    const match = matchRoute(url.pathname);
    if (!match) return; #2

    event.intercept({
      focusReset: "manual", #3
      scroll: "manual", #3

      async handler() {
        const page = await match.handler(match.params, {
          signal: event.signal #4
        });
        renderPage(page); #5

        document.title = page.title;
        focusMainHeading(); #6

        event.scroll(); #7
      }
    });
  });
}

See the complete interception pattern, including feature detection, route checks, an asynchronous handler, focus management, and manual scrolling. section 10.3.2

event.intercept() returns no promise. Observe completion with navigatesuccess or navigateerror, or use navigation.transition.finished during an in-progress navigation. Because Navigation API support is not universal, feature-detect it and provide a fallback, typically using the History API and manual link interception. section 10.3.5

How Vanilla Web covers it

How deep it goes
Details eligibility checks, asynchronous rendering, focus and scroll options, and completion observation, but not a promise returned by intercept().
Examples
Demonstrates route matching, skipping hashes and downloads, rendering a page, updating its title, focusing a heading, and scrolling.
What you can do after
Apply it via the Navigation API to render matched routes while retaining browser-managed URL and history updates.
How it connects
Connects the Navigation API to routing, same-document navigation, focus management, scroll restoration, and the History API fallback.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Vanilla Web. The section links point to the parts of the book it draws on.