The Escape Key Is Not a Strategy: Why Your Modals Need the Close Watcher API to Survive the Mobile Web

If you've spent more than five minutes building a modal or a drawer, you’ve probably written some variation of window.addEventListener('keydown', (e) => if (e.key === 'Escape') closeModal()). It works on your desktop browser. It feels like a standard. But the moment that same code hits a mobile device—specifically an Android device or a browser using gesture navigation—your "strategy" falls apart.

Desktop users have the Escape key. Mobile users have the "Back" button, the "Back" gesture, or even specific hardware buttons that don't map to a keyboard event. For years, web developers have been stuck in a cycle of hacky popstate listeners and fake history entries just to make a modal close when a user swipes from the edge of their screen.

The Close Watcher API is the platform’s long-overdue answer to this mess. It provides a unified way to listen for "dismissal requests" regardless of whether they come from a physical key, a gesture, or a software button.

The Back-Button-as-Escape Problem

We need to talk about why the current state of things is so broken. On Android, the system "Back" action is the universal way to dismiss something. If a modal is open, the user expects the Back button to close it. If they click it and the modal stays open while the underlying page navigates back to Google Search, you’ve just broken the fundamental UX of their device.

To solve this, developers often use the History API:

// The "Old Way" (Please stop doing this)
function openModal() {
  modal.show();
  window.history.pushState({ modalOpen: true }, '');
}

window.onpopstate = () => {
  if (modal.isOpen) {
    modal.close();
  }
};

This is brittle. It litters the user's browser history with "dead" entries. If the user clicks a link inside the modal, the history stack becomes a nightmare. If they refresh, the state is inconsistent. We are using a tool designed for multi-page navigation to solve a UI component dismissal problem. It’s a classic case of using a sledgehammer to drive a finishing nail.

Enter the Close Watcher API

The Close Watcher API (currently available in Chromium-based browsers) gives us a dedicated interface to handle these dismissals. It doesn't care if the user pressed Escape or swiped their thumb across the screen; it just tells you, "The user wants to close the current thing."

Here is the simplest possible implementation:

if ('CloseWatcher' in window) {
  const watcher = new CloseWatcher();

  watcher.onclose = () => {
    myModal.close();
  };
}

When the CloseWatcher is active, it intercepts the "Back" gesture on mobile and the "Escape" key on desktop. When either occurs, the onclose event fires.

The Lifecycle of a Watcher

A CloseWatcher isn't just a listener; it's an object with a lifecycle. You create it when your UI element appears, and you must destroy it when the element is removed.

const openDrawer = () => {
  drawer.classList.add('is-open');

  // Create the watcher when the drawer opens
  const watcher = new CloseWatcher();

  watcher.onclose = () => {
    closeDrawer();
  };

  // If the user closes the drawer via a "Cancel" button, 
  // we need to manually destroy the watcher.
  cancelBtn.onclick = () => {
    closeDrawer();
    watcher.destroy(); 
  };
};

If you forget to call .destroy(), the watcher stays active. If the user then tries to navigate back later, the browser might try to trigger a "close" event for a drawer that isn't even there anymore.

Handling the "Are You Sure?" Scenario

One of the most powerful features of the Close Watcher API is the oncancel event. We’ve all built forms where we want to warn the user before they discard their changes.

Previously, intercepting a Back button to show a "Save changes?" prompt was nearly impossible without major hacks. With CloseWatcher, it’s built-in.

const watcher = new CloseWatcher();

watcher.oncancel = (event) => {
  if (form.isDirty) {
    const confirmDiscard = confirm("You have unsaved changes. Close anyway?");
    if (!confirmDiscard) {
      event.preventDefault(); // This stops the 'close' event from firing
    }
  }
};

watcher.onclose = () => {
  hideForm();
};

The browser handles the timing. If preventDefault() is called during the cancel event, the close event never fires, and the "Back" action is effectively neutralized for that moment.

User Activation: The Security Catch

You can't just create a CloseWatcher whenever you want. If you could, malicious sites would create a million watchers to prevent you from ever navigating away using the Back button.

A CloseWatcher requires User Activation (a click, a tap, or a key press). If you try to create one on page load without the user doing anything, the browser will effectively ignore it or won't allow it to intercept system-level gestures.

This is usually fine because we typically open modals or drawers in response to a user click. However, if you are trying to show a "Subscribe to our newsletter" modal automatically after 10 seconds, the CloseWatcher might not work as expected until the user interacts with the page.

Real-World Implementation: A Robust Modal Component

Let's look at how this fits into a more realistic component structure. We want something that handles the API if it's available, but falls back gracefully for older browsers or Safari.

class SmartModal {
  constructor(element) {
    this.el = element;
    this.watcher = null;
  }

  show() {
    this.el.style.display = 'block';

    if ('CloseWatcher' in window) {
      this.watcher = new CloseWatcher();
      
      this.watcher.onclose = () => this.hide();
      
      this.watcher.oncancel = (e) => {
        if (this.el.querySelector('form')?.dataset.changed === 'true') {
          if (!confirm("Discard changes?")) {
            e.preventDefault();
          }
        }
      };
    } else {
      // Fallback for browsers that don't support CloseWatcher
      this._escapeHandler = (e) => {
        if (e.key === 'Escape') this.hide();
      };
      window.addEventListener('keydown', this._escapeHandler);
    }
  }

  hide() {
    this.el.style.display = 'none';
    
    if (this.watcher) {
      this.watcher.destroy();
      this.watcher = null;
    }

    if (this._escapeHandler) {
      window.removeEventListener('keydown', this._escapeHandler);
    }
  }
}

This covers both worlds. On a desktop running Chrome, you get the native behavior. On an Android phone, you get the native Back button support. In Safari (which hasn't implemented it yet), you still get the Escape key support.

Why Not Just Use <dialog>?

You might be thinking, "Doesn't the HTML <dialog> element already handle the Escape key?"

Yes, it does. But it has two major limitations that CloseWatcher solves:

1. System-level integration: Even the <dialog> element's native behavior struggled historically with the Android Back button. The Close Watcher API is actually the underlying mechanism that browsers are now using to make <dialog> behave correctly on mobile.
2. Non-dialog UI: Not every dismissible element is a <dialog>. Think about photo lightboxes, sidebar navigations, context menus, or even a full-screen video player. These are often built with <div> or <section> tags for styling or legacy reasons. CloseWatcher gives these non-dialog elements the same "first-class citizen" status for dismissal.

Layering and Grouping

What happens if you have a modal, and *inside* that modal, you open a confirmation pop-up?

The Close Watcher API handles this through a stack. If you create a second CloseWatcher while one is already active, the browser knows to trigger them in reverse order (LIFO - Last In, First Out).

1. User opens Modal A -> watcherA created.
2. User opens Confirm B -> watcherB created.
3. User hits Back button.
4. watcherB fires onclose, Confirm B hides.
5. User hits Back button again.
6. watcherA fires onclose, Modal A hides.

This eliminates the "Back button closes everything at once" bug that plagues many single-page applications.

Browser Support and Progressive Enhancement

As of right now, Close Watcher is a Chromium-first API (Chrome, Edge, Opera, Samsung Internet). Safari and Firefox have expressed interest, but it hasn't landed in stable yet.

Does this mean you shouldn't use it? Absolutely not.

This is the poster child for progressive enhancement. Adding a CloseWatcher doesn't break older browsers; it just makes the experience significantly better for the 70% of mobile users on Android.

The fallback is easy to write:

const supportsCloseWatcher = 'CloseWatcher' in window;

function handleOpen() {
  if (supportsCloseWatcher) {
    const watcher = new CloseWatcher();
    watcher.onclose = () => closeMe();
  } else {
    // Standard keyboard fallback
    window.addEventListener('keydown', legacyHandler);
  }
}

The "Gotcha": Accidental Navigation

There is one specific behavior you need to be aware of. When a CloseWatcher is active on a mobile browser, the first "Back" action is consumed by the watcher. If the user *really* wanted to go back to the previous page, they have to swipe or click "Back" twice.

This is intentional. It’s exactly how native Android apps work. When you have a drawer open in Gmail, the first back gesture closes the drawer. The second one exits the app. By using CloseWatcher, you are finally bringing that native expectation to the web.

However, if you create a CloseWatcher for something subtle (like a small tool-tip), it might feel like the page is "hijacking" the back button. Use it for significant UI states—modals, drawers, lightboxes, and menus—not for every tiny hover state.

Summary

The Escape key was never meant to be a comprehensive mobile strategy. Relying on it is like trying to build a touch interface that only responds to right-clicks.

The Close Watcher API is the missing link between web UI and mobile OS gestures. It allows us to:
- Stop polluting the History API with dummy entries.
- Handle "Are you sure?" prompts cleanly with .oncancel.
- Support Android Back buttons and gestures natively.
- Manage stacks of nested UI elements without complex custom logic.

If you care about the mobile experience—and let’s be honest, that’s where most of your users are—it’s time to stop listening for keys and start watching for closes.