跪拜 Guibai
← All articles
CSS · HTML · Frontend

Why Your Modal Still Pops: The Three-Piece `display: none` Transition Fix, Measured in Chrome

By htzyl206 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Native CSS modal animations now work across modern browsers, but the common one-liner tutorials leave developers shipping modals that fade in and pop out, which feels broken. Understanding the three (or four) distinct mechanisms prevents silent failures that are hard to spot without frame-by-frame measurement.

Summary

Fading a modal in and out with pure CSS has been possible since Chrome 117, but tutorials usually give only one line — `transition: display .3s allow-discrete` — and that often leaves exit animation broken. The root cause: `display: none` elements have no box, so no intermediate frames exist for `opacity` to transition through. The fix requires three independent pieces working together: putting `display` in the transition list, adding `transition-behavior: allow-discrete` as a license, and defining `@starting-style` to give the entry a starting frame.

Measured with Puppeteer on Chrome 152, the article shows that entry and exit are separate mechanisms: entry needs `@starting-style` because there's no previous value; exit only needs `display` and `allow-discrete` because the element still exists. It also identifies five silent failures that look correct but break animation — a misplaced `transition-behavior` that gets reset by the shorthand, `@starting-style` overridden by a later rule, an invalid value that drops the whole declaration, a `display: flex` base rule that overrides the browser's default `dialog:not([open])` style, and `::backdrop` not animating without its own `display` and `overlay` transitions.

For top-layer elements like `<dialog>` and `popover`, a fourth property, `overlay`, is essential to keep the element in place during exit. Rapid clicking doesn't get stuck; it jitters. Compatibility is nuanced: `transition-behavior` and `@starting-style` entered Baseline in 2024, but `display` being actually transitionable only appears in Safari 18 and Firefox's support is unlabeled. The article offers a copyable modal CSS with a `@supports` fallback layer and a clear check order to debug entry versus exit failures.

Takeaways
— `display: none` elements have no box, so `opacity` transitions can't produce intermediate frames unless `display` itself is included in the transition list.
— `transition-behavior: allow-discrete` gives `display` a license to participate in a transition; without it, `display` switches instantly.
— `@starting-style` provides the starting frame for entry, but is not needed for exit because the element still exists then.
— Writing `transition-behavior` before the `transition` shorthand resets it to `normal`; it must come after.
— `@starting-style` placed before the target rule gets overridden; it should come after the target rule or use a more specific selector.
— An invalid value in a `transition` declaration causes the entire declaration to be discarded, including working parts like `opacity`.
— Setting `display: flex` on a base `dialog` rule overrides the browser's default `dialog:not([open]) { display: none }`.
— `::backdrop` doesn't follow its parent's transition; it needs its own `display` and `overlay` with `allow-discrete` for smooth fade.
— Top-layer elements like `<dialog>` and `popover` need `overlay` in the transition list to avoid dropping to the document flow mid-exit.
— Rapidly toggling animates back and forth without getting stuck, but the jitter can be mitigated by shortening the exit duration.
— `transition-behavior` and `@starting-style` are Baseline since 2024-08-06, but `display` actually transitioning only works in Safari 18 (and Chrome/Edge 117+), while Firefox support remains unlabeled.
— Don't use `:modal` to check if an element is still in the top layer; it becomes false immediately on close.
— A copyable modal CSS uses `transition-behavior` after the shorthand, includes `display` and `overlay` with `allow-discrete`, and wraps `::backdrop` separately.
— Missing one of the three pieces is worse than writing no animation: one-way animation makes the modal feel inconsistent.
Conclusions

The article's frame-by-frame testing debunks the common belief that adding `transition: display .3s allow-discrete` alone is enough; entry and exit are governed by different mechanisms that must be verified separately.

The shorthand reset issue is a classic CSS gotcha that silently flips `transition-behavior` back to `normal`, producing a symptom opposite to missing `@starting-style` — a useful debugging branch point.

The `overlay` property is often ignored because it's non-settable, but for top-layer elements it's the difference between an element staying in place and teleporting to the top of the page mid-animation.

The compatibility table reveals that spec support and actual transition behavior are not aligned across browsers; developers should rely on measured results rather than `CSS.supports`.

The recommendation to make only one-direction animation rather than none is a strong design opinion: inconsistent UX is worse than no animation.

Concepts & terms
transition-behavior: allow-discrete
A CSS property that allows discrete properties (like `display`) to participate in transitions. It acts as a permission flag; without it, `display` changes instantly with no intermediate frames.
@starting-style
An at-rule that specifies the starting style for an element on its first paint or when `display` changes from `none` to another value. It provides the initial frame for entry transitions that would otherwise have no previous value to interpolate from.
overlay property
A browser-controlled property indicating whether an element is in the top layer (e.g., `<dialog>` or `popover`). It cannot be set, but including it in `transition-property` with `allow-discrete` delays its removal, keeping the element in place during exit animations.
From the discussion
Featured comments
组合搭配函数

The three-piece set plus overlay is explained thoroughly; the root cause of modal exit jumping was right here. Following the troubleshooting sequence at the end of the article step by step can save you from several pitfalls.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗