SpunkArt
Front-end and everyday web

How CSS keyframe animations work

A CSS animation is a named set of keyframes plus a few properties that say how long it runs, how it eases and how often it repeats. You can write every part by hand once you know what each property controls.

The two halves of an animation

Every CSS animation has two parts. The @keyframes rule describes what changes. The animation properties on an element describe when and how that change plays.

@keyframes fade-up {
  from { opacity: 0; transform: translateY(12px); }
  to   { opacity: 1; transform: translateY(0); }
}

.notice {
  animation: fade-up 0.8s ease-out 0.2s 1 both;
}

The keyframe names from and to are aliases for 0% and 100%. You can add any stops in between, such as 40%, and the browser fills the gaps by interpolating each property.

What each animation property does

PropertyControlsTypical value
animation-nameWhich @keyframes rule to playfade-up
animation-durationLength of one cycle0.8s
animation-timing-functionThe speed curve inside one cycleease-out
animation-delayWait before the first cycle; a negative value starts part-way through0.2s
animation-iteration-countHow many cycles run1, 3, infinite
animation-directionForward, reverse or back-and-forthalternate
animation-fill-modeWhether the first or last keyframe applies outside the active timeboth
animation-play-statePause or runpaused

In the shorthand, the first time value is always the duration and the second is the delay. The order of the other values is flexible, but a consistent order makes code easier to read.

Working out the total running time

total time = delay + duration × iteration count

Example. animation: pulse 0.8s ease-in-out 0.2s 3 alternate;

  • Cycles: 0.8 s × 3 = 2.4 s
  • Add the delay: 2.4 + 0.2 = 2.6 s until the animation ends
  • With alternate, cycles 1 and 3 play forward and cycle 2 plays in reverse, so the element finishes at the to state.

A fractional count is allowed. With a duration of 1 s and a count of 2.5, the element stops half-way through the third cycle.

Timing functions and cubic-bezier

The keywords ease, ease-in, ease-out, ease-in-out and linear are shortcuts for curves. You can write your own with cubic-bezier(x1, y1, x2, y2). The x values must stay between 0 and 1 because they represent time. The y values may go outside that range, which creates a small overshoot, for example cubic-bezier(0.34, 1.56, 0.64, 1). For mechanical, frame-by-frame motion such as a sprite sheet, use steps(n) instead of a curve.

How to build one by hand

  1. Decide the start state and the end state of the element.
  2. Write them as from and to in a @keyframes rule with a clear name.
  3. Add the animation shorthand with a duration first. Start with 200 to 500 ms for interface feedback.
  4. Choose ease-out for things that enter and ease-in for things that leave.
  5. Set animation-fill-mode: both if the element must not flash its unanimated state.
  6. Test with the browser DevTools animation panel, which lets you slow playback down and scrub.

Smooth and respectful motion

Browsers can animate transform and opacity without recalculating layout, so prefer them over top, width or margin. At 60 frames per second each frame has about 16.7 ms (1000 ÷ 60), and layout work inside that budget is what causes stutter.

Some people get dizzy or distracted by motion. Respect the operating system setting:

@media (prefers-reduced-motion: reduce) {
  .notice { animation: none; }
}

Common mistakes

  • Writing the delay before the duration in the shorthand, which swaps the two times.
  • Forgetting the fill mode, so the element jumps back to its first state when the animation ends.
  • Animating height: auto, which does not interpolate. Animate transform: scaleY() or a measured max height instead.
  • Running decorative infinite loops that never stop and pull attention from the content.

Questions

When should I use a transition instead?

Use a transition when a property changes between two states because of an event, such as hover or a class change. Use keyframes when the motion needs more than two stops, should play on load, or should repeat.

Can JavaScript control a CSS animation?

Yes. You can add or remove a class, change animation-play-state, or listen for the animationend event to run code when a cycle finishes.