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
| Property | Controls | Typical value |
|---|---|---|
animation-name | Which @keyframes rule to play | fade-up |
animation-duration | Length of one cycle | 0.8s |
animation-timing-function | The speed curve inside one cycle | ease-out |
animation-delay | Wait before the first cycle; a negative value starts part-way through | 0.2s |
animation-iteration-count | How many cycles run | 1, 3, infinite |
animation-direction | Forward, reverse or back-and-forth | alternate |
animation-fill-mode | Whether the first or last keyframe applies outside the active time | both |
animation-play-state | Pause or run | paused |
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
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 thetostate.
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
- Decide the start state and the end state of the element.
- Write them as
fromandtoin a@keyframesrule with a clear name. - Add the
animationshorthand with a duration first. Start with 200 to 500 ms for interface feedback. - Choose
ease-outfor things that enter andease-infor things that leave. - Set
animation-fill-mode: bothif the element must not flash its unanimated state. - 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. Animatetransform: scaleY()or a measured max height instead. - Running decorative
infiniteloops 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.