dialog animation improvements

Author: mdo

js/src/dialog-base.js

@@ -98,10 +98,17 @@ class DialogBase extends BaseComponent {
 
     this._isTransitioning = true
     this._hideElement()
-    this._onAfterHide()
 
     this._queueCallback(() => {
+      // For subclasses that defer close() until the exit transition ends
+      // (so the dialog stays in the top layer with its ::backdrop), close()
+      // happens here instead of in _hideElement().
+      if (this._element.open) {
+        this._closeAndCleanup()
+      }
+
       this._element.classList.remove('hiding')
+      this._onAfterHide()
       this._isTransitioning = false
       EventHandler.trigger(
         this._element,
@@ -163,6 +170,20 @@ class DialogBase extends BaseComponent {
     // Without this, the navbar's `:not([open])` transition-kill rule
     // would prevent the slide-out animation.
     this._element.classList.add('hiding')
+
+    // Subclasses can defer close() until after the exit transition by
+    // returning true from _shouldDeferClose(). This is needed for the
+    // native modal <dialog> centered case: close() removes the dialog
+    // from the top layer immediately, which strips its auto-centering
+    // and the ::backdrop, breaking the exit animation.
+    if (!this._shouldDeferClose()) {
+      this._closeAndCleanup()
+    }
+  }
+
+  // Closes the native <dialog> and tears down body-scroll prevention.
+  // Safe to call multiple times — close() is a no-op on a closed dialog.
+  _closeAndCleanup() {
     this._element.close()
     this._openedAsModal = false
 
@@ -172,6 +193,13 @@ class DialogBase extends BaseComponent {
     }
   }
 
+  // Hook: return true to keep the dialog in the top layer (i.e., delay
+  // calling close()) until the exit transition completes. The base class
+  // closes synchronously; Dialog overrides this for animated modal cases.
+  _shouldDeferClose() {
+    return false
+  }
+
   _triggerBackdropTransition() {
     const hidePreventedEvent = EventHandler.trigger(
       this._element,

js/src/dialog.js

@@ -84,6 +84,16 @@ class Dialog extends DialogBase {
     this._element.classList.remove(CLASS_NAME_NONMODAL)
   }
 
+  // Keep the dialog in the top layer until the exit transition ends. This
+  // preserves the browser's modal centering and the native ::backdrop, both
+  // of which disappear synchronously the moment close() is called. Without
+  // this, the dialog would jump to the top of the page and the backdrop
+  // blur would vanish instantly while the dialog faded — making the exit
+  // animation appear to skip entirely.
+  _shouldDeferClose() {
+    return this._isAnimated()
+  }
+
   _onCancel() {
     EventHandler.trigger(this._element, EVENT_CANCEL)
   }

scss/_dialog.scss

@@ -117,7 +117,11 @@ $dialog-sizes: defaults(
       // Open state: visible and faded in.
       // Entry transition: visibility flips visible immediately (0s, no delay),
       // then opacity and transform animate in.
-      &[open] {
+      // The :not(.hiding) qualifier lets the exit transition fall back to the
+      // base "exit" state above while [open] is still present (the JS keeps
+      // the dialog in the top layer during the exit so the ::backdrop and
+      // the browser's modal centering remain intact).
+      &[open]:not(.hiding) {
         overflow: visible;
         visibility: visible;
         opacity: 1;
@@ -129,8 +133,12 @@ $dialog-sizes: defaults(
         transform: none;
       }
 
-      // Static backdrop "bounce" animation (modal dialogs only)
-      &.dialog-static {
+      // Static backdrop "bounce" animation (modal dialogs only). Qualified
+      // with [open] (to outrank the open-state `transform: none` selector
+      // which now also includes `:not(.hiding)`) and `:not(.hiding)` (so
+      // a backdrop click while the dialog is mid-exit doesn't fight the
+      // slide-out transform).
+      &[open].dialog-static:not(.hiding) {
         transform: scale(1.02);
       }
 
@@ -140,6 +148,14 @@ $dialog-sizes: defaults(
         backdrop-filter: blur(var(--dialog-backdrop-blur));
         @include backdrop-transitions(var(--dialog-transition-duration), var(--dialog-transition-timing));
       }
+
+      // Exit: fade the native backdrop out alongside the dialog. The dialog
+      // is kept in the top layer (and thus the ::backdrop is still rendered)
+      // for the duration of the exit transition.
+      &.hiding::backdrop {
+        background-color: transparent;
+        backdrop-filter: blur(0);
+      }
     }
 
     // Instant variant — no transitions, just snap visibility
@@ -150,8 +166,11 @@ $dialog-sizes: defaults(
       }
     }
 
-    // Open state base (always applies, regardless of animation mode)
-    &[open] {
+    // Open state base (always applies, regardless of animation mode).
+    // Excluded while .hiding is present so the animated exit (above) can
+    // fall through to the base "exit" state — for instant dialogs, .hiding
+    // is removed synchronously after close() so this still applies normally.
+    &[open]:not(.hiding) {
       overflow: visible;
       visibility: visible;
       opacity: 1;

site/src/content/docs/components/dialog.mdx

@@ -15,13 +15,11 @@ The Dialog component leverages the browser's native `<dialog>` element, providin
 
 Key features of the native dialog:
 
-- **Native modal behavior** via `showModal()` with automatic focus trapping
-- **Built-in backdrop** using the `::backdrop` pseudo-element
-- **Escape key handling** closes the dialog by default
-- **Accessibility** with proper focus management and ARIA attributes
-- **Top layer rendering** ensures the dialog appears above all other content
-
-Native `<dialog>` elements support two methods: `show()` opens the dialog inline without a backdrop or focus trapping, while `showModal()` opens it as a true modal in the browser's top layer with a backdrop, focus trapping, and Escape key handling. Bootstrap's Dialog component uses `showModal()` to provide the expected modal experience.
+- **Modal or inline** via `showModal()` / `show()` — `modal: true` (default) promotes the dialog to the browser's top layer with a backdrop and focus trapping; `modal: false` renders it inline.
+- **Built-in backdrop** using the `::backdrop` pseudo-element (modal only); set `backdrop: "static"` to lock clicks outside, or `backdrop: false` to hide it.
+- **Escape key handling** closes the dialog by default; set `keyboard: false` to disable.
+- **Accessibility** — focus is trapped inside modal dialogs and returned to the trigger on close, with native `<dialog>` ARIA semantics.
+- **Animated open and close** — circumvent browser restrictions by using a `.hiding` class to keep dialogs in the top layer during close so the exit transition (including `::backdrop`) are animated properly.
 
 <Callout name="info-prefersreducedmotion" />