[FEE-11101] @starting-style — Entry Animations Without JavaScript
INFO
Define where an element's transition begins, so dialogs, toasts, and dropdowns can animate into view with pure CSS and no JavaScript timing hacks.
Baseline Newly Available
Supported in Chrome 117+, Firefox 129+, Safari 17.5+. Use progressive enhancement for older browsers.
Context
CSS transition animates between two computed states. To do so, it needs a "before" value and an "after" value for every property being animated. This works perfectly when an element is already in the DOM and visible: changing opacity from 1 to 0, or transform from none to translateY(-8px), gives the browser a clear before and after.
The problem arises with elements that are hidden via display: none. When an element has display: none, the browser does not render it. It has no computed box, no geometry, and no interpolable property values. When you switch it to display: block, CSS transitions have no starting state to animate from. The element simply appears at its final state instantly.
For years, the workaround was a JavaScript timing hack:
// Show the element first (establishing a computed state)
element.style.display = 'block';
// Then, on the next frame, add the class that triggers the transition
requestAnimationFrame(() => element.classList.add('visible'));The requestAnimationFrame callback fires after the browser has painted the element at its initial state, giving the transition a "before" value to interpolate from. This works, but it is fragile: it couples what should be a pure CSS presentation concern to JavaScript, and the timing is technically implementation-dependent.
Chrome 117 introduced two related capabilities simultaneously:
@starting-style: an at-rule that explicitly declares the initial computed values for a transition when an element first becomes visible.- Animatable
display: thedisplayproperty can now participate in CSS transitions, allowingdisplay: none→display: blockto be part of a smooth animated sequence.
A toast that slides down and fades in when it appears, or a dialog that animates open, can now be written in pure CSS instead of JavaScript. The Example below builds the dialog case using the Popover API, which is supported in Chrome, Firefox, and Safari. The entry animation works in all three; the exit's top-layer cleanup degrades in Firefox and Safari, which lack overlay support (covered below). The Deep Dive returns to the toast case, which needs a Safari-specific caveat covered there.
Visual
The core mechanic is what computed value the browser has to interpolate from at the moment an element becomes visible.
| Stage | Without @starting-style (display: none → block) | With @starting-style |
|---|---|---|
| Computed style before the change | None; no box exists | None; no box exists |
| Value the browser interpolates from | None. There is nothing to interpolate from, so the transition skips straight to the end value | The values declared in @starting-style (e.g. opacity: 0) |
| First rendered frame | Final state, instantly | @starting-style state |
| End of the transition duration | Same as the first frame; no animation occurred | Final state, animated |
Example
A dialog using the Popover API that fades in and slides down from above when opened, and fades out and slides up when closed. The full animation is pure CSS: the popovertarget attribute on the buttons handles open/close without any JavaScript.
Popover and <dialog> elements render in the browser's top layer, a stacking context above the normal document that guarantees they render above everything else regardless of z-index. The CSS overlay property controls an element's membership in that top layer and, like display, is a discrete property that needs allow-discrete to participate in a transition. As of 2026-07, overlay is supported in Chrome and Edge only; Firefox and Safari drop it from the transition list silently, which affects the exit animation there (see the walkthrough below and the Deep Dive).
<button popovertarget="my-dialog">Open dialog</button>
<div id="my-dialog" class="dialog" popover>
<p>Hello from the dialog!</p>
<button popovertarget="my-dialog" popovertargetaction="hide">Close</button>
</div>/* Base layout — always applied */
.dialog {
padding: 2rem;
border-radius: 8px;
border: 1px solid #e2e8f0;
background: #fff;
box-shadow: 0 8px 24px rgb(0 0 0 / 0.12);
max-width: 480px;
width: 90%;
}
@media (prefers-reduced-motion: no-preference) {
/* Final (open) state */
.dialog:popover-open {
opacity: 1;
transform: translateY(0);
}
/* Transition declaration — includes display so the popover
can animate out before being removed from the top layer */
.dialog {
transition:
opacity 0.25s ease,
transform 0.25s ease,
display 0.25s allow-discrete,
overlay 0.25s allow-discrete;
}
/* Entry: starting state when the dialog first becomes visible */
@starting-style {
.dialog:popover-open {
opacity: 0;
transform: translateY(-12px);
}
}
/* Exit: animate toward the hidden state before display:none applies */
.dialog:not(:popover-open) {
opacity: 0;
transform: translateY(-12px);
}
}How the entry works
When the popover opens:
- The browser applies
:popover-opento the dialog, making it part of the top layer. - Because
display: none→ displayed is a discrete change withallow-discrete, the display change happens immediately at the start of the transition. @starting-styleprovides the initial computed values:opacity: 0,transform: translateY(-12px).- The transition interpolates from the
@starting-stylevalues to the:popover-openvalues (opacity: 1,transform: translateY(0)) over 250 ms.
How the exit works
When the popover closes:
- The browser removes
:popover-open, which activates the:not(:popover-open)rule (opacity: 0,transform: translateY(-12px)). - The
displaytransition (withallow-discrete) delays that discrete change until the end, so the element stays visible while the opacity and transform animate. Theoverlaytransition does the same for top-layer membership, but only in Chrome and Edge: Firefox and Safari do not support theoverlayproperty, so in those browsers the top layer can be removed before the 250 ms animation finishes and the exit can appear clipped. See theoverlaynote in the Deep Dive. - After 250 ms (in browsers where
overlaydelays removal), the transition ends, the top-layer membership anddisplay: noneapply, and the element disappears.
Progressive enhancement fallback
Without the @media (prefers-reduced-motion: no-preference) wrapper, the popover still opens and closes correctly. It simply appears and disappears without animation. Browsers that do not support @starting-style also show the popover without animation rather than breaking, so no guard is strictly required.
For stricter progressive enhancement, guard on transition-behavior: allow-discrete rather than :popover-open: Popover shipped in every engine before @starting-style did, so a :popover-open check produces false positives (see Browser Support).
@supports (transition-behavior: allow-discrete) {
@media (prefers-reduced-motion: no-preference) {
/* animation rules here */
}
}Best Practices
- MUST include
@starting-stylealongside anytransitionthat animates element entry. Without it, there is no starting state, and the transition does not play on first render or when transitioning fromdisplay: none. - MUST use the
allow-discretekeyword when transitioningdisplayorvisibility. These are discrete properties: they do not interpolate numerically. Theallow-discreteflag tells the browser to delay the discrete change until the end of the transition (for exit) or apply it immediately at the start (for entry). Syntax:transition: opacity 0.3s, display 0.3s allow-discrete. - MUST NOT use
@starting-stylefor exit animations. It only applies when an element is first rendered or transitions out ofdisplay: none. For exit, define the hidden state in a selector rule targeting the hidden state (e.g.,:not(:popover-open)). - SHOULD wrap all entry/exit animation CSS in
@media (prefers-reduced-motion: no-preference)to avoid triggering vestibular disorders in sensitive users. - SHOULD use
@starting-stylenested inside the element's existing rule block where the spec allows nesting. This keeps the starting state co-located with the transition declaration and is easier to maintain. - MAY also use
@starting-stylefor elements that are newly inserted into the DOM, not just those transitioning fromdisplay: none. The rule fires whenever the element first gets a computed style, though this specific path was reported not to fire in Safari 17.6 (MDN browser-compat-data issue #25643, which remains open as of 2026-07); treat it as progressive enhancement there.
Design Thinking
Why CSS transitions could not animate entry before
CSS transitions require two computed style snapshots: the value before the change and the value after. The browser captures the "before" snapshot, then applies the new CSS, captures the "after" snapshot, and interpolates between them over the specified duration.
When an element has display: none, it is outside the formatting context entirely. A display: none element has no rendered box, so the browser holds no interpolable values for it. The moment display changes to block, the browser creates a new layout box from scratch. There is no "before" snapshot, so no transition fires.
How JavaScript hacks compensated
The requestAnimationFrame trick works because it forces the browser to commit a rendering frame with the element at its initial state before the transition-triggering class is added. After that initial paint, the "before" snapshot exists and the transition fires normally.
Other workarounds included:
visibility: hiddeninstead ofdisplay: none:visibilityis an animatable discrete property, so elements remained in the layout flow (taking up space) even when hidden, preserving the computed box. This solved the transition problem but had layout side effects.@keyframesanimation withanimation-fill-mode: forwards: using@keyframes from { opacity: 0 }sidesteps the transition problem entirely since keyframes always have an explicit starting frame. The cost is more verbose CSS and less composability with thetransitionproperty.- Double
requestAnimationFrame: some libraries used two nested rAF calls to guarantee two rendered frames before triggering the class, working around inconsistent behavior in certain browsers.
Why @starting-style is the right model
@starting-style is explicit about intent. It answers the question: "where does this element start animating from?" directly in CSS, without relying on paint-timing coincidences or JavaScript orchestration. The browser's job becomes unambiguous: use the values in @starting-style as the interpolation start point, then transition to the values in the element's normal rule.
This also makes the code easier to understand: the starting state, the ending state, and the transition timing are all in the stylesheet.
Deep Dive
@starting-style and Shadow DOM
@starting-style works inside shadow roots. Rules declared inside a <style> element within a shadow tree apply to elements within that shadow root when they first become visible, following the same scoping rules as all other shadow DOM styles.
@starting-style applies to transitions only, not @keyframes
@keyframes animations already have an explicit first frame: the from or 0% block. They do not need @starting-style. The at-rule is exclusively about providing the "before" snapshot for CSS transitions. If you switch from a transition-based entry animation to a @keyframes-based one, remove @starting-style and use from { opacity: 0; transform: translateY(-12px); } in the keyframe block instead.
A common point of confusion: animation-fill-mode: backwards fills the from keyframe before the animation starts, which superficially resembles what @starting-style does for transitions. They are unrelated mechanisms. animation-fill-mode operates on keyframe timelines, while @starting-style operates on the transition system's before/after snapshot model.
Nesting @starting-style inside a selector
The spec supports nesting @starting-style inside the rule that it applies to:
.dialog:popover-open {
opacity: 1;
transform: translateY(0);
transition: opacity 0.25s, transform 0.25s, display 0.25s allow-discrete;
@starting-style {
opacity: 0;
transform: translateY(-12px);
}
}This nested form keeps the starting state co-located with the final state and transition declaration. It is equivalent to the non-nested form and supported wherever @starting-style is supported (Chrome 117+, Firefox 129+, Safari 17.5+).
Specificity inside @starting-style
Rules inside @starting-style have the same specificity as the equivalent rules outside the block. @starting-style { .dialog:popover-open { opacity: 0; } } has the specificity of .dialog:popover-open: one class and one pseudo-class. This means you can override @starting-style values with higher-specificity selectors just as you would with normal CSS.
The overlay property
overlay controls whether an element is in the browser's top layer. It is a discrete property, like display, and also requires allow-discrete to participate in transitions:
transition: opacity 0.3s, display 0.3s allow-discrete, overlay 0.3s allow-discrete;Including overlay in the transition ensures the top layer (the backdrop and stacking context that Popover and <dialog> elements inhabit) also animates out gracefully. Without it, the top-layer context collapses immediately on close, which can cause the exit animation to appear clipped or to jump.
As of 2026-07, overlay is supported in Chrome and Edge 117+ only. MDN documents it as not Baseline because it does not work in some of the most widely used browsers, and neither Firefox nor Safari implement it. In those two engines the declaration is dropped from the transition list, so the exit animation loses the protection overlay provides and can clip the same way it would if the property were omitted deliberately. Treat overlay as a Chromium-only enhancement: include it for the browsers that support it, but do not rely on it to guarantee a clean exit animation everywhere.
Interaction with visibility vs display
If your hidden state uses visibility: hidden rather than display: none, you do not need allow-discrete. visibility is already handled by the CSS transition system as a discrete-but-transitioning property. You also do not strictly need @starting-style for visibility-based show/hide, because visibility: hidden elements still have a computed box and property values for transitions to start from. @starting-style is most valuable for the display: none / Popover / <dialog> cases where no prior computed state exists.
Applying @starting-style to newly inserted DOM nodes
@starting-style is not limited to elements toggling display. It also fires when an element is first inserted into the DOM, for example a toast notification created dynamically via JavaScript:
const toast = document.createElement('div');
toast.className = 'toast';
toast.textContent = 'File saved.';
document.body.appendChild(toast);.toast {
position: fixed;
bottom: 1.5rem;
right: 1.5rem;
padding: 0.75rem 1.25rem;
background: #1e293b;
color: #fff;
border-radius: 6px;
opacity: 1;
transform: translateY(0);
transition: opacity 0.3s ease, transform 0.3s ease;
}
@media (prefers-reduced-motion: no-preference) {
@starting-style {
.toast {
opacity: 0;
transform: translateY(8px);
}
}
}When the element is appended to the DOM, the browser assigns its first computed style. @starting-style intercepts that moment, providing opacity: 0 and transform: translateY(8px) as the starting values. The transition then plays from those values to the normal rule values (opacity: 1, translateY(0)), producing the entry animation with no requestAnimationFrame required.
For the exit, set opacity: 0 imperatively (or via a class) before removing the element, and listen for the transitionend event to call element.remove().
Safari caveat: reported against Safari 17.6, @starting-style applies correctly to elements present at initial page load but does not fire for elements inserted into the DOM afterward, including this toast pattern. The tracking issue, MDN's browser-compat-data issue #25643, remains open as of 2026-07. Chrome and Firefox do not have this problem. Treat the toast's entry animation as progressive enhancement in Safari: the toast still appears, just without sliding or fading in, so nothing breaks, but do not depend on this path for a required visual effect while the issue remains open.
Browser Support
| Browser | First version | Notes |
|---|---|---|
| Chrome | 117 | |
| Firefox | 129 | |
| Safari | 17.5 | |
| Edge | 117 | Chromium-based |
Feature detection
@supports at-rule(@starting-style) is the direct way to ask "does this browser support the @starting-style at-rule?" As of 2026-07, it works: Chrome and Edge 148 shipped at-rule() support to the stable channel on 2026-05-05. Firefox and Safari do not yet implement at-rule(), so the check still returns false in those two engines even though they do support @starting-style itself; for those engines, one of the proxies below is still needed.
A shortcut used in some guides is testing :popover-open selector support instead, on the assumption that @starting-style and the Popover API shipped together. They did not. Popover shipped first in every engine (Chrome 114, Safari 17.0, Firefox 125), and @starting-style followed later (Chrome 117, Safari 17.5, Firefox 129). A browser in the gap, Safari 17.0 through 17.4 for example, passes a :popover-open check but has no @starting-style, so the guard is a false positive there.
transition-behavior: allow-discrete is a closer proxy. It shipped in the same Chrome and Firefox versions as @starting-style, and only one Safari point release earlier (17.4 versus 17.5):
@supports (transition-behavior: allow-discrete) {
/* @starting-style and allow-discrete transitions */
}const supported = CSS.supports('transition-behavior', 'allow-discrete');This still has a narrow false-positive window in Safari 17.4, but it is far tighter than the popover check. For engines that do not yet implement at-rule() (Firefox and Safari, as of 2026-07), the Space Toggle technique documented by Bram.us (see References) is a further fallback that reads @starting-style support without relying on a co-shipped feature.
Browsers that do not support @starting-style silently skip the starting-state block. Entry transitions do not play; elements appear at their final state instantly instead of breaking.
Internet Explorer and legacy Edge (pre-Chromium) do not support @starting-style. These browsers are outside the support matrix for most new projects, but if your target includes them, treat all entry animations as purely decorative and ensure the element's default CSS state is fully visible without animation.
Related Topics
- FEE-11100 Scroll-driven Animations: a complementary CSS animation feature. Scroll-driven animations handle progress through a scroll timeline;
@starting-stylehandles the moment an element first appears. Both eliminate JavaScript from CSS presentation logic. - FEE-11001 CSS Anchor Positioning: both features are commonly combined with the Popover API. CSS Anchor Positioning controls where a popover appears;
@starting-stylecontrols how it animates into that position.
References
- MDN Contributors, "@starting-style," MDN Web Docs (2024). https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@starting-style
- Una Kravets and Joey Arhar, "Four new CSS features for smooth entry and exit animations," Chrome for Developers (2023). https://developer.chrome.com/blog/entry-exit-animations
- L. David Baron and Brian Birtles, "CSS Transitions Module Level 2," W3C Editor's Draft, CSS Working Group. https://drafts.csswg.org/css-transitions-2/
- Bramus Van Damme, "Feature detect CSS @starting-style support," Bram.us (2024). https://www.bram.us/2024/07/11/feature-detect-css-starting-style-support/
- MDN Contributors, "
@starting-styledoes not apply to elements inserted after page load in Safari," browser-compat-data issue #25643, GitHub. https://github.com/mdn/browser-compat-data/issues/25643 - MDN Contributors, "overlay," MDN Web Docs. https://developer.mozilla.org/en-US/docs/Web/CSS/overlay