Skip to content

Transition: overlay stays mounted forever when closed during its enter transition and React commits after the next frame #3902

Open

Description

@mattisfat

Version: @headlessui/react 2.2.9 (code unchanged in 2.2.10)

What happens: show flips to false while the enter transition is still
running. useTransition reverses it: run() sets the closed/enter flags, and
one requestAnimationFrame later waitForTransition captures
getAnimations(). If React hasn't committed the flag change by then, which
happens when the main thread is busy, the capture contains the old enter
transitions. The commit then starts the reverse transitions. When the
captured ones settle, done() runs with inFlight set and finds the reverse
transitions still running (isTransitioning), so it returns. Nothing calls
it again, so the element is never unmounted.

Effect: the element stays mounted with data-closed data-enter data-transition. For Dialog, the invisible wrapper keeps covering the
page and swallows clicks, and neither Escape nor clicking removes it.

Reproduction: a busy main thread is simulated by delaying React's
scheduler messages (MessagePort.prototype.postMessage) by 80ms from the
moment of closing; animation frames still run on time. Closing a
Transition-wrapped Popover, Dialog or Listbox while its enter transition
is still running (40–100ms after opening, in our tests) then strands it.
Without the delay it never does. Minimal example (React 19.3, esbuild):

import { useState } from "react";
import { createRoot } from "react-dom/client";
import { Dialog, DialogPanel } from "@headlessui/react";

// Simulate a busy main thread: once armed, delay React's scheduler
// messages by 80ms. Animation frames still run on time.
const post = MessagePort.prototype.postMessage;
MessagePort.prototype.postMessage = function (...args) {
  if (!window.__busy) return post.apply(this, args);
  setTimeout(() => post.apply(this, args), 80);
};

function App() {
  const [open, setOpen] = useState(false);
  const [result, setResult] = useState("");
  const run = () => {
    window.__busy = false;
    setResult("");
    setOpen(true);
    setTimeout(() => {
      window.__busy = true; // only the close is slow
      setOpen(false);
      setTimeout(() => {
        window.__busy = false;
        setResult(document.querySelector('[role="dialog"]') ? "STUCK" : "unmounted");
      }, 1500);
    }, 60);
  };
  return (
    <>
      <style>{`.panel{transition:opacity 200ms}.panel[data-closed]{opacity:0}`}</style>
      <button onClick={run}>Open, then close after 60ms</button>
      <output>{result}</output>
      <Dialog open={open} onClose={() => setOpen(false)}>
        <DialogPanel transition className="panel">Panel</DialogPanel>
      </Dialog>
    </>
  );
}

createRoot(document.getElementById("root")).render(<App />);

In Chromium this reports STUCK 10 times out of 10. With the delay
disabled it reports unmounted 10 times out of 10. The stuck element is
<div role="dialog" data-headlessui-state="open" …>, still in the DOM.

Suggested fix: in waitForTransition, after the captured transitions
settle, re-check getAnimations() and wait again until no CSSTransition
is running before calling done(). We ship this as a local patch; with it,
the example above reports unmounted 10 times out of 10.

Activity

  1. blakesteve commented on Oct 30, 2026

    @blakesteve

    We hit this in a component library on 2.2.9 and measured it with real key presses (Playwright, Chromium and WebKit on macOS, React 19.2). The dialog has the usual shape: transition on DialogBackdrop and DialogPanel, opacity and scale, 300ms in and 200ms out. We pressed Escape at points spread through the entrance:

    • At a load average of 13 to 20: 2 stuck in 1,200 presses, one in each engine.
    • At 3 to 5: none in 1,800.

    Both stuck dialogs matched the description here: data-closed data-enter data-transition on the panel, no transition running, afterLeave never called, and the backdrop taking every click.

    A second symptom of the same single read. With no interruption at all, the leave is sometimes skipped. In CI (Linux WebKit, a loaded runner), afterLeave fired 152ms after Escape, inside a 200ms leave, with the panel still at opacity 1. Our reading: if no transition has started by the getAnimations() read one frame after run() (for instance because the closed flag hasn't reached the DOM yet, as in this issue), waitForTransition finds nothing and calls done() at once.

    On #3895. It reads the transitions again each time a batch settles, so a reverse transition that replaces the captured enter transitions is waited for. That looks like it fixes the stuck case. It doesn't change the first read, though: that still happens one frame after run(), and if it finds no transitions, done() is still called at once with no second look. So the skipped leave above would remain. One option: when that first read is empty but the element's computed transition-duration isn't 0s, look again on a later frame (a bounded number of times) before calling done().

    Our workaround for the stuck case, for anyone who needs one now: render the Dialog with a key, and if it's still mounted with no transition running after the leave's length plus a margin, change the key. That remounts it closed.

  2. ARasskazov-intra commented on Nov 7, 2026

    @ARasskazov-intra

    We hit this too, on @headlessui/react 2.2.10 with React 19.3 and Chromium on macOS. Our setup is Dialog + DialogBackdrop transition + DialogPanel transition, 300 ms in and 200 ms out. Two things may help, as neither is in this thread yet.

    A double click reaches it, with no injected delay. The first click opens the dialog. The second lands on the backdrop inside the opening, so it closes as an outside click. In Playwright's headless shell, with real mouse events and no throttling, we got 6 stuck in 50 and 4 stuck in 40 on one menu item, and 3 in 42 on another. Machine load average was between 12 and 78. In full Chromium (new headless) it was 0 in 95 without injection, and 3 in 6 with the 40 ms scheduler delay. Script-driven click() never stuck: 0 in 156, across CPU throttling and added long tasks. So plain load wasn't enough for us. It looks like frame order after a real input event, though we haven't read Chromium's code for that.

    A trace of one natural failure, with no injection:

    ms Step
    6360 prepare, show=true
    6373 waitForTransition captures the enter transitions
    6442 prepare, show=false, inFlight true, so cancelled
    6529.6 run sets the closed flags through React state
    6530.4 waitForTransition runs, and the element has no data-closed yet, so it captures the old enter transitions
    then React commits data-closed, the old transitions are replaced, their finished promises settle
    6533.8 done(): cancelled, hasPendingTransitions true, returns, and nothing waits again

    The state left behind matches this issue: data-closed data-enter data-open data-transition on the backdrop and panel, opacity 0, aria-modal="true" on the root, and the full-screen wrapper taking every click. The focus trap also stays live. Escape did nothing in one of the two screens we tried. In the other, it closed the parent overlay, which unmounted the dialog.

    A re-check after the wait fixed it for us. On a throwaway copy of dist/hooks/use-transition.js:

    Promise.allSettled(i.map(o => o.finished)).then(() => { n || (D(e) ? t.add(M(e, r)) : r()) })
    Check Before After
    Injected delay, close at 100 ms 3 stuck in 10 0 in 10
    Injected delay, close at 50 ms 5 stuck in 12 0 in 25
    Real double click, no injection see above 0 in 50

    That's the same idea as #3895, but we didn't test #3895 itself. We also can't speak to the skipped-leave case raised in the comment above.

    waitForTransition and the early return in done() are unchanged on main, and 2.2.10 is still the latest release. Could a maintainer take a look at #3895?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions