CSS at-ruleAt-rules

@starting-style

Describes the style a transition starts from when an element appears on the page. This lets new elements slide in smoothly.

On this page

Example

#
CSS
.modal[open] {
  opacity: 1;
  scale: 1;
  transition: opacity 0.3s, scale 0.3s;
}

@starting-style {
  .modal[open] {
    opacity: 0;
    scale: 0.9;
  }
}

.modal::backdrop {
  background: rgb(0 0 0 / 0.6);
}
Preview

Click “Claim reward”. The window appears smoothly because @starting-style provides the initial state. It closes immediately: a smooth close also needs display with allow-discrete in the transition, as in the example below.

Definition and usage

#

A transition (transition) needs two states: the previous one and the new one. An element that has just landed on the page or stopped having display: none has no previous state, so the browser shows it in its final look right away. The @starting-style rule supplies the missing state: the transition starts from these styles when the element is first displayed.

The syntax is simple. You give the element its target styles and transition, and in @starting-style you repeat the selector with the starting values, e.g. opacity: 0 and translate: 0 20px. The rule can be written separately or nested inside the selector. Starting styles do not have higher specificity, so place the @starting-style block after the target rule.

It is most often combined with transition-behavior: allow-discrete for the display property. Then the element not only appears smoothly but also disappears smoothly, because display: none kicks in only after the transition ends. This is how <dialog> windows and elements with the popover attribute are animated.

The rule concerns transitions only. @keyframes animations start on their own when an element appears, so they do not need an initial state. A browser that does not know @starting-style will simply show the element right away, with no error.

Syntax

#
Syntax
selector {
  transition: opacity 0.3s;
}

@starting-style {
  selector { opacity: 0; }
}

Entrance effects

#
  • opacity: 0

    a smooth fade-in

    The element keeps appearing anew, and each time it starts from full transparency. It disappears instantly, because the exit is not animated.
  • translate: 0 24px

    sliding in from below

    It starts 24 px lower and transparent. The element slides into place, like a notification.
  • scale: 0.3

    a springy pop-in

    The element starts scaled down, and a cubic-bezier curve with a value above 1 gives a slight overshoot, like a spring.
  • filter: blur(8px)

    sharpening, nested syntax

    The rule can be nested inside the element’s selector. The declarations inside then apply to the same element, and the order is correct on its own.
  • without @starting-style

    no animation

    transition alone is not enough. The element has no previous state, so the transition has nowhere to start from and the element appears immediately.
  • display + allow-discrete

    entrance and exit

    With allow-discrete on display, the browser waits to hide the element until the end of the transition. The element appears smoothly and disappears smoothly.
  • [popover]

    a popover

    Click the button. An open popover matches :popover-open, and @starting-style makes it slide in from below. You close it by clicking outside or pressing Esc.

Entrance effects in practice

#

opacity: 0

The element keeps appearing anew, and each time it starts from full transparency. It disappears instantly, because the exit is not animated.
.demo { transition: opacity 0.6s; }

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

translate: 0 24px

It starts 24 px lower and transparent. The element slides into place, like a notification.
.demo {
  transition: opacity 0.6s, translate 0.6s;
}

@starting-style {
  .demo { opacity: 0; translate: 0 24px; }
}

scale: 0.3

The element starts scaled down, and a cubic-bezier curve with a value above 1 gives a slight overshoot, like a spring.
.demo {
  transition: scale 0.5s cubic-bezier(0.3, 1.6, 0.6, 1);
}

@starting-style {
  .demo { scale: 0.3; }
}

filter: blur(8px)

The rule can be nested inside the element’s selector. The declarations inside then apply to the same element, and the order is correct on its own.
.demo {
  transition: opacity 0.6s, filter 0.6s;

  @starting-style {
    opacity: 0;
    filter: blur(8px);
  }
}

without @starting-style

transition alone is not enough. The element has no previous state, so the transition has nowhere to start from and the element appears immediately.
.demo { transition: opacity 0.6s; }

display + allow-discrete

With allow-discrete on display, the browser waits to hide the element until the end of the transition. The element appears smoothly and disappears smoothly.
.demo {
  transition: opacity 0.6s,
    display 0.6s allow-discrete;
}
.demo.hidden { opacity: 0; }

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

[popover]

Click the button. An open popover matches :popover-open, and @starting-style makes it slide in from below. You close it by clicking outside or pressing Esc.
[popover]:popover-open {
  transition: opacity 0.3s, translate 0.3s;
}

@starting-style {
  [popover]:popover-open {
    opacity: 0;
    translate: 0 16px;
  }
}

More examples

#
A window that opens and closes smoothly
CSS
.modal {
  opacity: 0;
  translate: 0 24px;
  transition:
    opacity 0.3s,
    translate 0.3s,
    display 0.3s allow-discrete,
    overlay 0.3s allow-discrete;
}

.modal[open] {
  opacity: 1;
  translate: 0;
}

@starting-style {
  .modal[open] {
    opacity: 0;
    translate: 0 24px;
  }
}
Preview

The window slides in from below and disappears the same way. display with allow-discrete waits to hide it until the end of the transition, and overlay, where the browser supports it, keeps the closing window above the page until the animation ends.

Browser support

#

Newly available · since 2024

Works in the current versions of all major browsers. Older versions may not support it.

  • Chrome
  • Edge
  • Firefox
  • Safari

Good practices

#
  • Place the @starting-style block after the rule you animate, or nest it inside. Starting styles do not have higher specificity, so a rule written later would override them.
  • For a smooth exit, add display with allow-discrete to the transition, and for dialogs and popovers also overlay. @starting-style alone handles only the entrance.
  • Ordinary hover transitions do not need this rule. Use it only when an element appears on the page or comes out of display: none.

Related entries

#

Spotted a mistake or missing an example? Write to us.