CSS animations can serve to delight website visitors if done well. However, they can sometimes be a hassle to learn and set up depending on how elaborate you want them to be. As with many things in CSS, sometimes CSS animations act in ways you just don’t expect.
For instance, CSS animations require you to write syntax in a specific way, and to include certain rules to get things to look right. Plus, there’s a chance that animations may not work on certain browsers, or that your animation can negatively affect page performance.
To help you out, we’ve compiled some common issues that beginner developers (and sometimes experienced ones!) face when creating CSS animations, and we’ll show you how you can fix them.
How to Solve Common CSS Animation Issues
Whether your animation isn’t working as intended, or just isn’t working at all, here are some reasons why and how you can resolve them:
No @keyframes Rule
In CSS animations, the @keyframes rule defines how the animation looks, or, more specifically, which element styles change and when. Without this rule, your element won’t have any animation to use. Check that your @keyframes rule exists and that its name matches that of animation-name for the targeted element.
In the example below, try uncommenting the @keyframes rule to activate the animation.
See the Pen css animation issues: no keyframes by Christina Perricone (@hubspot) on CodePen.
Animation Duration Not Set
Even if you’ve assigned a keyframes rule to an element, it still may not appear to play if you haven’t set an animation-duration. By default, a CSS animation cycle is zero seconds long. To override this, add an animation-duration rule to your targeted element with a seconds value, in the same block as animation-name.
Below, try removing the comments around animation-duration to fix the animation.
See the Pen css animation issues: no animation duration by Christina Perricone (@hubspot) on CodePen.
Animation Plays Only Once
Similarly, a CSS animation will only cycle one time unless you specify a number of iterations with the animation-iteration-count parameter. This value can be a specific number of cycles or infinite if you want the animation to loop forever.
Try uncommenting the animation-iteration-count rule below.
See the Pen css animation issues: animation plays once by Christina Perricone (@hubspot) on CodePen.
Animated Element Resets at the End
Say you have an animation that starts in one state — like black text — and ends in another state — like purple-colored text. If this animation only plays once, you’d probably want the color to stay purple after the animation completes.
However, by default, CSS animations will change back to the element’s pre-animated state after an animation finishes. This can make the animation look broken.
The good news is that CSS animations have a solution, the animation-fill-mode property. This property instructs the animated element to retain the styles from the first and/or last keyframe of the animation.
Watch the example below. After the text color changes to purple, you’ll see it flip back to black. But, if we uncomment the rule animation-fill-mode: forwards; we see the text remain purple. This is because animation-fill-mode: forwards; takes the last keyframe style (purple text) and applies it to the element after the animation cycle.
See the Pen css animation issues: animation resets by Christina Perricone (@hubspot) on CodePen.
Animation Starts Too Soon
Sometimes you may want to add a short delay before the start of an animation for a better user experience. Accomplish this with the animation-delay property. Below, the animation has a delay of 4s (four seconds).
See the Pen css animation issues: animation starts too soon by Christina Perricone (@hubspot) on CodePen.
Non-Animatable CSS Properties
Another reason why your animation isn’t working might be that you’re attempting to animate a CSS property that isn’t animatable. Check our list of animatable CSS properties for the property you’re trying to animate and make sure it’s there. Otherwise, you'll need to find another way to achieve a similar effect.
Alternatively, you can look up the property in Mozilla’s CSS properties reference, then look for an Animation type under Formal definition. This documentation will show you the different ways the property can be animated.
CSS Animation Not Supported
CSS animations work on most modern mobile and desktop browsers. However, your animations may not work if you’re using an older browser or a version of your browser that hasn’t been updated in several years, simply due to lack of browser support.
If your browser is updated and you're still having issues, try adding your animation rules with vendor prefixes in addition to your original rules and try the animation again. For example, the -webkit- vendor prefix (for Chrome and Safari browsers) looks like this when applied to an animation.
As this code demonstrates, always place the declarations with vendor prefixes before the declarations without vendor prefixes, so the vendor prefix rules don’t override the original rules.
If you’re comfortable with JavaScript, you can also reference this guide to detecting CSS animation support in your browser.
CSS Shorthand Written Incorrectly
CSS shorthand is a good way to write cleaner CSS and reduce the amount of code in your file. The animation property is shorthand for these CSS properties:
- animation-duration
- animation-name
- animation-delay
- animation-direction
- animation-fill-mode
- animation-iteration-count
- animation-play-state
- animation-timing-function
Two values — one for animation-duration and one for animation-name — are required. Besides those, the order of the values determines which value is assigned to which animation property. Misaligned values could result in an animation behaving differently than you expect. So, if using the animation shorthand property, make sure its values are listed in the right order.
Multiple Misaligned Animation Property Values
It’s possible to assign several different animations to the same element with multiple values separated by commas. In the example below, I’ve applied three different animations to one p element.
See the Pen css animation issues: multiple animations by Christina Perricone (@hubspot) on CodePen.
Notice how animation-name and animation-duration have three values each. The three values of animation-name assign three different keyframes rules to the p element. The three values of animation-duration set lengths for each animation cycle respectively — the first animation, change-color, is eight seconds long, and the other two are five seconds long.
When creating animations this way, make sure you’re ordering your values correctly for each animation-* declaration. Otherwise, your animations won’t work how you intended.
If you want to apply the same value of a property to all animations, you only need to include one value in that property’s declaration. I’ve done this with animation-iteration-count in the above example — all three animations will run infinitely.
Slow Performance
CSS animations tend to be better for performance than other types of web animations. However, not all CSS animations are equal, and some animated styles will slow performance down more than others.
Most simple CSS animations should have no noticeable impact on page load times. However, the more effects you add to your animation, the more likely you are to run into performance issues.
To avoid poor performance, Google recommends limiting your use of animations that trigger repaints. A paint is when the browser creates the visual display of a web page pixel-by-pixel on the screen. Paints use a relatively large amount of processing power, so you should limit the number of repaints caused by animations as much as you can.
Unfortunately, most animatable CSS properties trigger a repaint when changed. The exceptions to this are transform (for things like scale, rotation, and position) and opacity, which can be animated with minimal effect on performance. Here’s a reference for which CSS properties trigger repaints when animated.
Still, don’t let that dissuade you from scrapping animations altogether. If you’re having speed problems, it’s likely because you’re trying to execute many at once or applying an animation to one large element or group of elements. On websites, CSS animations are best when used subtly to enhance the experience, so consider whether you need an elaborate animation to engage visitors.
Debug CSS Animations with Developer Tools
It’s also worth mentioning that some browsers are equipped with debugging tools for CSS animations. If you use Google Chrome or Firefox, check your developer tools for an Animations inspector.
This tool lets you restart, slow down, pause, and scrub through a timeline of the animation to see exactly what the browser is doing. This can be useful if you’re still having issues getting your animations to work, especially more complex ones.
Troubleshoot CSS Animations
Animations can sometimes be frustrating to get right — the good news is that this makes it all the more satisfying when they do work. As we’ve seen, there are several potential causes for animation errors, but this can usually be fixed by correcting a piece of syntax or adding a new rule.
CSS animations can add a lot of character to a static web page, so it’s worth doing a bit of troubleshooting to make them perfect.
