@starting-style: Animating an Element's Very First Style Change

Add an element to the DOM with opacity: 1 and a transition on opacity, and it will appear at full opacity with no fade — every time. The transition is syntactically perfect and the browser ignores it. This behaviour is not a bug and it is not a race condition you can fix by deferring the insertion; it falls out of how the transition algorithm is specified. This page, part of the CSS Transition Fundamentals section, explains the before-change style rule that causes it and shows how the @starting-style at-rule supplies the missing frame so entry motion works for newly inserted nodes, elements leaving display: none, and anything promoted into the top layer.

The narrow scenario: a toast, dropdown, or freshly appended list item that must ease in on the first frame it exists, without a script forcing a reflow between two class changes.

Why the browser refuses to animate, and when to accept it

A CSS transition is defined as an interpolation between a before-change style and an after-change style. The engine computes both, diffs them property by property, and starts an animation for each transitionable property whose value differs. An element rendered for the first time has no before-change style at all: there is no earlier computed style in the box tree to diff against. With only one style available, nothing differs, so no transition is created and the element paints at its final value.

The historic workaround was to insert the element in its hidden state, read a layout property such as offsetHeight to force a style recalculation, and only then add the visible class — two style resolutions manufactured by JavaScript so the diff has something to compare. That trick is fragile: it depends on a synchronous reflow that a framework's batching or a requestAnimationFrame scheduler can easily reorder, and it costs a forced synchronous layout on every insertion. @starting-style replaces the whole dance with a declarative rule that tells the engine, in CSS, what the before-change style should have been. There is no accessibility tradeoff to the mechanism itself, but the motion it enables is still motion, so it belongs under the same reduced motion preferences guard as everything else. Skip @starting-style when the element's arrival is not something the user needs to perceive — an instant appearance is cheaper and often calmer.

Where the before-change style comes from

The diagram contrasts the two resolution paths. Without a starting rule the engine finds no earlier style and commits directly to the final one. With @starting-style it has a synthetic previous style to diff against, so ordinary transition machinery takes over.

A complete working implementation

The demo below reveals a panel with a checkbox, which is enough to exercise both halves of the lifecycle: opening the panel is a first style change (it was display: none, so it has no before-change style), and closing it is an ordinary transition toward a discrete display value. Toggle it a few times and watch that the entry motion repeats every time, not just once.

<label class="reveal__label">
  <input type="checkbox" class="reveal__input"> Show notification
</label>

<div class="reveal__panel">
  <strong>Saved</strong>
  <span>Your changes are on the server.</span>
</div>

.reveal__label { display: inline-flex; align-items: center; gap: .5rem; cursor: pointer; }

/* The "after-change" style: what the panel looks like once it is open. */
.reveal__panel {
  display: block;
  margin-top: 1rem;
  padding: .9rem 1rem;
  border: 1px solid currentColor;
  border-radius: 10px;
  opacity: 1;
  translate: 0 0;
  transition:
    opacity 260ms ease,
    translate 260ms cubic-bezier(.2, .8, .2, 1),
    display 260ms allow-discrete;
}
.reveal__panel span { display: block; font-size: .9rem; margin-top: .2rem; }

/* Closed state — display:none makes this a discrete change, hence allow-discrete above. */
.reveal__input:not(:checked) ~ .reveal__panel {
  display: none;
  opacity: 0;
  translate: 0 -8px;
}

/* The before-change style: the values the panel animates FROM on its first rendered frame.
   Without this block the panel would appear fully opaque and in place, instantly. */
@starting-style {
  .reveal__input:checked ~ .reveal__panel {
    opacity: 0;
    translate: 0 -8px;
  }
}

Three details are load-bearing. The @starting-style selector targets the panel in its open state, because that is the style change being made — the rule describes where that state comes from. The closed-state declarations are not redundant with it: they are what the panel transitions to on the way out. And display 260ms allow-discrete is required because a property going to display: none would otherwise remove the box before opacity had a chance to move; the mechanics of that keyword are covered in transitioning display with allow-discrete.

The key technique: a rule that applies for exactly one frame

@starting-style is not a state selector and it does not participate in the cascade the way a normal rule does. Its declarations are consulted only while the engine is assembling a before-change style for an element that does not have one, and they are thrown away immediately afterwards. That is why you cannot use it to "set a default" — one frame later the value inside it has no effect whatsoever, and the element's ordinary rules win.

The trigger condition is worth stating precisely, because it is broader than "when the element is created". Any first style change qualifies: an element inserted into the DOM, an element whose computed display moves from none to a rendered value, and an element promoted into the top layer by showPopover(), showModal(), or the popover attribute. All three produce an element that is newly rendered from the style engine's point of view, and all three are therefore covered by the same rule.

The at-rule has two writable forms. The standalone form contains complete selectors:

@starting-style {
  .toast { opacity: 0; }
}

The nested form lives inside the element's own rule and inherits its subject:

.toast {
  opacity: 1;
  transition: opacity 200ms ease;
  @starting-style { opacity: 0; }
}

Prefer the nested form for component CSS. It keeps the starting values physically next to the values they animate toward, and it cannot drift out of sync with the selector when the class name changes.

Variation: entry motion for a popover in the top layer

A popover is the sharpest case, because the element is both newly rendered and moved into the top layer. The overlay property that tracks top-layer membership is discrete, so a clean exit needs it listed alongside display.

.tip {
  opacity: 1;
  scale: 1;
  transition:
    opacity 180ms ease,
    scale 180ms cubic-bezier(.2, .9, .3, 1),
    display 180ms allow-discrete,
    overlay 180ms allow-discrete;

  /* Nested starting rule: the values used on the popover's first rendered frame. */
  @starting-style {
    &:popover-open { opacity: 0; scale: .94; }
  }
}
.tip:not(:popover-open) { opacity: 0; scale: .94; }

@media (prefers-reduced-motion: reduce) {
  .tip { transition-duration: 1ms; }
}

Note the reduced-motion branch collapses the duration rather than removing the transition outright. Setting transition: none would also strip the allow-discrete behaviour and re-introduce the abrupt removal; a 1ms duration keeps the discrete sequencing intact while making the movement imperceptible. The same pattern extends to anchored overlays covered in the popover attribute and CSS styling.

Browser support note

@starting-style shipped alongside transition-behavior in Chrome and Edge 117+ and Firefox 129+, and in Safari 17.5+ (one point release after transition-behavior, which landed in 17.4). It is available in every evergreen engine as of mid-2026. Nesting a @starting-style block inside a style rule requires the same support as CSS nesting generally, which is comfortably older than the at-rule itself. The fallback is inherently benign: an engine that does not recognise the at-rule discards it as an unknown construct, the element appears at its final style with no entry motion, and nothing else in the sheet is affected. Because the failure mode is "no animation" rather than "broken layout", an @supports at-rule(@starting-style) guard is optional rather than necessary.

FAQ

Why does a transition never run the first time an element is rendered? A transition interpolates between a before-change style and an after-change style, and a freshly rendered element has no before-change style for the engine to diff against. With only one style available nothing differs, so no transition is created and the final value paints immediately.

Where do I put the @starting-style rule? Either as a standalone at-rule containing a full selector, or nested inside the rule for the element itself. The nested form is scoped to that rule's subject, which keeps the starting values next to the values they animate toward and avoids accidentally matching other elements sharing the class.

Does @starting-style also apply when an element becomes visible again? Yes. It applies to any first style change, which includes an element moving from display: none to a rendered state and an element being promoted into the top layer, not just the initial page render.

Does @starting-style work with keyframe animations? No. It feeds CSS transitions only, because only transitions need a before-change style. A keyframe animation already declares its own opening frame and runs on element creation without extra help.

Related

• CSS Transition Fundamentals — the parent guide covering transition syntax and property selection.
• Transitioning display with allow-discrete — the exit half of the lifecycle this page starts.
• CSS transition timing functions — pick an easing curve that suits an arrival rather than a departure.
• CSS-only accordions and disclosure — a disclosure widget whose panel needs the same first-render treatment.
• Anchor positioned tooltips — position the overlays that these entry animations reveal.