Using SVG/SMIL Animation Elements

All the attributes for declaring animations#

There are a lot of different attributes for controlling SVG/SMIL animations. There is a more detailed reference, with all the syntax details, in “Animation Elements” section of our markup guide; this is a more conceptual overview.¹ The attributes can be grouped into the following categories:

Setting the target element and attribute#

The target element is identified with an xlink:href cross-reference; it defaults to the animation element’s parent (which could be a shape, group, <use> element or pretty much any other element in SVG).

The target attribute or style property is set with attributeName. By default, the animation will affect the style property, if one exists by that name. You can use attributeType="XML" to force the browser to animate the XML attribute instead of a CSS property by the same name. This is important for animating width and height and so on.

Setting the new value(s)#

The changed value(s) for your attribute or style is set with one of the to, by, or values attributes, and optionally with from:

• to is the final value of the property/attribute

• by is an amount to increase or decrease the value

• from is the initial value (which defaults to the base value on the element)

• values is a sequence of keyframe values—including the “from” and “to” values—as a semicolon-separated list (if you use it, the other attributes are ignored)

The fill="freeze" attribute forces the ending value to be preserved indefinitely, unless you set a different animation on the same element or restart this animation.

Setting duration and repeats#

The dur attribute sets the duration time of a single cycle of the animation; without a fixed duration, the animation won’t progress past the from value. You can cause that cycle to repeat by setting repeatCount (a number of cycles) or repeatDur (a total duration time). By default (without either repeat* attribute), the animation only runs once.

Either repeatCount or repeatDur can be indefinite (not “infinite”) for unlimited repeats. If you set both repeat measurements, the first one to finish terminates the animation. You can also set a max (maximum) total duration time or a min (minimum) time; however, min can’t cause extra repeats, it only affects indefinite animations ended with end.

Setting beginning and ending times#

Animations have a begin time and an end time, which causes all repeats to end. begin is by default at 0s, relative to the document loading time; end is by default determined by the duration and repeat attributes. Both values can be a semicolon-separated list of multiple times.

In addition to beginning or ending at a specified time, you can begin or end an animation in response to an event. Events are specified using the DOM event name, like mouseover (for a mouseover event on the animation’s target element) or button1.click (for a click event on an element in the document with id of button1). Animation elements create begin and end events, plus numbered repeat events like repeat(1), so you can set one animation to begin or end in sync with another. You can also set time offsets from an event, like begin="otherAnimation.end - 1s" to start this animation one second before the other animation is due to end.

Multiple begin times or event triggers can cause an animation to interrupt itself; the restart attribute can limit restarts, to only whenNotActive (i.e., not currently running) or never at all.

Setting pacing between keyframes#

By default, multiple keyframe values are evenly distributed in the duration of an animation cycle, and the actual values are interpolated in a linear fashion between each keyframe. You can change the keyframe positions with keyTimes, which take a semicolon-separated list of numbers between 0 and 1 (like the percentages in CSS keyframes, but converted to decimals).

You can switch interpolation methods with the calcMode attribute, to discrete, paced, or spline (the default is linear). “Spline” interpolation is cubic Bézier easing, and only works if you also set keyTimes and keySplines. The values in keySplines are cubic Bézier control points (four numbers, like the ones in the CSS cubic-bezier() function), with multiple sets of four numbers (one for every pair of consecutive values) in a semicolon-separated list.

Setting additive effects#

The additive and accumulate attributes allow animations or repeats to sum together; we’ll discuss them in “Additive and accumulative animations”.

Are you confused yet?

Learning SVG/SMIL takes a lot of practice and a lot of double-checking the specs. There are so many possible options, but there are also lots of annoying cross-dependencies, like not being able to use from without either to or by, and not being able to use keySplines without keyTimes, even when you aren’t changing the keyTimes default!

So why bother?

Because there are some things that SVG/SMIL can do really easily that are currently difficult or impossible with CSS animations. The next couple sections look at some of those cases.

Synchronized animation timelines#

One of the biggest benefits of SVG/SMIL relative to CSS animations are the synchronized timing options. These allow you to create an entire script of different short animations.

To demonstrate, we’ll create an animated logo, similar to the “stingers” that movie and TV production studios use at the beginning or ends of films. The logo is about as basic as a logo can get, as shown in Figure 19-X1: a circle, with the words “Circle Games” arranged in a circular <textPath>.

To give this simple logo a little pizzazz, we’re going to:

• animate the circle up from nothing (like we did in Example 19-2), but then have it bounce bigger and smaller for a few seconds before settling down.

• Rotate the text into place around the circular text-path, fading it in to full opacity as the letters appear.

• Hold the full logo in place a few seconds.

• Fade the text out again, but without moving it.

• Shrink the circle down to a dot, with some easing effects to give it a jump at the end.

• Roll the dot off the side of the screen, accelerating as it goes.

Figure 19-X2 shows the animation sequences as a series of stills, taken at one-second intervals for twenty seconds. For something a little more exciting, view the final live animation.

Before we get into the code, we’ll introduce one more animation element.

Although the <animate> element is the general workhorse for most attribute animations, for simple discrete changes it is usually easier to use <set>.

A <set> element applies the to value to the target attribute or property for as long as the animation is active. In other words, it sets the attribute to the new value for a specified amount of time (dur) or until the end trigger. There is no transition time—the change is always discrete—and there is no way to apply a sequence of values or to change the value by a relative amount.

In other words, the main benefit of <set> is that it lets you avoid writing calcMode="discrete" over and over again. Also, it makes your code a little more clear.

So the following <set> element would ensure that its parent element disappears when the element with id="button1" is clicked, and isn’t displayed again until the element with id="button2" is clicked:

<set attributeName="display" to="none"
     begin="button1.click"
     end="button2.click" />

(Of course, for accessibility purposes you’d want make sure that button1 and button2 are actually <a> links that can be “clicked” with the keyboard, too.)

In Example 19-X1, we use a <set> to hide the logo text until it is ready to be animated in. The remaining changes are all defined with <animate> elements, that modify the circle’s radius (r), or its horizontal position (cx), the text’s opacity, and the <textPath>’s startOffset position.

<svg xmlns="http://www.w3.org/2000/svg" xml:lang="en"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     width="100%" height="100%" viewBox="-220 -220 440 440">
    <title>Reveal and Disappear Animated Logo</title>
    <circle id="c" r="190"
            fill="darkOrchid" stroke="plum" stroke-width="16" /> 
    <defs>
        <path id="p" d="M0,125 A125,125 0 0,1 0,-125
                               A125,125 0 0,1 0, 125Z" />
    </defs>                                                      
    <text id="t" dy="0.7ex" text-anchor="middle"
          font-size="48pt" font-family="Verdana"
          fill="white">
        <textPath id="tp" xlink:href="#p"
                  startOffset="50%">Circle Games</textPath></text>

    <set     id="textHide" xlink:href="#t"
             attributeName="visibility" to="hidden"
             end="textFadeIn.begin" />                   
    <animate id="circleGrow" xlink:href="#c"
             attributeName="r"
             values="0;215;100;205;140;195;170;190"
             dur="5s"/>                                  
    <animate id="textPathSlide" xlink:href="#tp"
             attributeName="startOffset"
             from="-20%" to="50%"
             dur="4s" begin="circleGrow.end - 1s" />     
    <animate id="textFadeIn" xlink:href="#t"
             attributeName="opacity" from="0" to="1"
             dur="3s" begin="textPathSlide.begin" />     
    <animate id="textFadeOut" xlink:href="#t"
             attributeName="opacity" to="0" fill="freeze"
             dur="2s" begin="textPathSlide.end + 3s" />  
    <animate id="circleShrink" xlink:href="#c"
             attributeName="r" to="8" fill="freeze"
             dur="3s" begin="textFadeOut.end + 0.1s"
             calcMode="spline" keyTimes="0;1"
             keySplines="0.2,0.9,0.9,0.5" />             
    <animate id="circleMove" xlink:href="#c"
             attributeName="cx" by="-500" fill="freeze"
             dur="3s" begin="circleShrink.end"
             calcMode="spline" keyTimes="0;1"
             keySplines="0.5,0,0.8,0" />                 
</svg>

The base values for all those attributes are defined such that, without SVG/SMIL support, the static logo is shown, with the circle full size and the text neatly centered.

Animating complex motion#

In addition to <animate> and <set>, there are two specialized SVG animation elements for creating animated transformations:

<animateTransform>

Applies one particular transformation function to the target element. The type attribute specifies which type of transformation (translate, scale, rotate, etc.), while the to, from, by, or values attributes specify the parameters to the transformation.

<animateMotion>

Moves the target element, similar to translational (and rotational) transformations. However, instead of defining the transformation using the normal syntax, you describe where you want the element to go. The path of the motion can be defined as a series of translations, or as an SVG path through the coordinate system.

You can optionally make the shape auto-rotate to match the angle of the path (similar to how the letters are rotated in a <textPath> layout), with rotate="auto".

In SVG 1.1, <animateTransform> and <animateMotion> are the only way to get smooth transitions of tranformations: the spec did not define rules for animating the full transformation lists from one value to another. Those rules are defined in the CSS Transforms Module, so you could theoretically animate transforms with <animate>, but only if any of the browsers had updated their implementations.

We’ll show an example of <animateTransform> in the next section, when we discuss additive animations. For this section, we’re focusing on <animateMotion>.

In the original SMIL version of <animateMotion>, you specified x and y translation distances in the to, from, by, or values attributes.

You can do that with SVG/SMIL, but it is mostly equivalent to an <animateTransform> with type="translate". The differences are:

• You can rotate the shape to match the direction of the motion (but this isn’t supported in Chrome).

• You can use lengths with units in <animateMotion> values (but this isn’t supported in Chrome).

• The default calcMode is paced instead of linear (Chrome gets this part correct).

A paced animation means that the speed stays steady throughout the entire animation. In contrast, with linear and spline modes, the total duration is divided up into separately-timed transitions for each value in the list. Consider the following animation:

<animateMotion values="0,30; 40,0; 80,30; 0,30"
               rotate="auto"
               dur="9s" repeatCount="indefinite" />

Those four (x,y) pairs in values, with the last pair repeating the first, create an isoceles triangle, as shown in Figure 19-X3. The sides of the triangle have lengths of 50, 50, and 80 units; the total path length is 180 units.

A linear mode would divide the total animation into 3 equal steps (unless you set keyTimes). For the 9s animation, that would mean 3 seconds for each side of the triangle. The shape would move more slowly on the shorter sides and faster on the long side.

For the paced animation, the total 180-unit distance would be divided by the 9s total duration; any keyTimes attribute would be ignored. The shape moves 20 units per second along the entire triangle.

The most interesting use of <animateMotion> is to apply motion along an SVG path. This allows you to define motion along curves which can’t be broken down into a series of linear translations. It also means that Chrome will support auto-rotation.

The motion path you use can be set two ways:

• in the path attribute of the <animateMotion> element, using SVG path data syntax; or,

• as a cross reference to a <path> element, specified using the xlink:href attribute on an <mpath> element that is a child of the <animateMotion>.

The <mpath> element has no other attributes; it only exists because the main animation elements already had an xlink:href attribute for identifying the target element—and because SVG 1 insisted on using xlink:href for all cross references other than style properties.

Example 19-3, in the book, used <animateMotion> and <mpath> to create an infinitely spinning loader, of multiple beads moving along the same path.

Additive and accumulative animations#

Compared to the complex patterns you can create with <animateMotion>, a single <animateTransform> element isn’t particularly interesting. It can only apply a single transformation function: either a rotation or a translation or a scale or a skew.

You could create complex motion with <animateTransform> by nesting elements with different transformations: an element with a translation inside a group with a rotation, for example. Nesting elements like this is currently the recommended approach for animating complex transformations with CSS.

But sometimes, you don’t want to add all those nested <g> elements. And sometimes, it’s not even an option—for example, inside a <clipPath> where groups are still forbidden.

SVG/SMIL has a solution: additive animations. Multiple independent animation elements, animating the same property on the same element, that can add together in their effect.

You define an additive animation by setting the additive attribute to sum.

The default value for additive is replace: animations that start later replace earlier animations of the same property on the same element. For multiple animations that start at the same time, the last element in the document wins (similar to CSS rules).

Example 19-X2 uses additive <animateTransform> animations to create a complex motion pattern. The example creates the appearance of X-Ray glasses or goggles, seeing through a photograph (of one of the authors, Kurt). Figure 19-X4 shows sample screenshots.

<svg xmlns="http://www.w3.org/2000/svg" xml:lang="en"
     xmlns:xlink="http://www.w3.org/1999/xlink"
     viewBox="0 0 384 643" width="384px" height="643px">
    <title>X-Ray Scanner</title>
    <image xlink:href="TopHatKurt.jpg" width="100%" height="100%"/>
    <image xlink:href="TopHatSkull.jpg" width="100%" height="100%"
           clip-path="url(#cp)" />                         
    <path id="goggles"
          d="M0-30 A75,75 0 1,1 0,30 A75,75 0 1,1 0,-30Z"
          fill="green" fill-opacity="0.4"
          stroke="green" stroke-width="4">                 
        <animateTransform attributeName="transform"
            type="translate" values="200,40;200,600;200,40"
            dur="10s" repeatCount="indefinite" />          
        <animateTransform attributeName="transform"
            type="translate" values="-50,0;50,0;-50,0"
            dur="3s" repeatCount="indefinite"
            additive="sum"/>                               
        <animateTransform attributeName="transform"
            type="rotate" values="-10;10;-10"
            dur="7s" repeatCount="indefinite"
            additive="sum"/>                               
    </path>
    <clipPath id="cp">
        <use xlink:href="#goggles" />                      
    </clipPath>
</svg>

Example 19-X2 demonstrates another limitation of the SMIL syntax: in order to create an alternating (back-and-forth) animation, you need to repeat values in an a;b;a sequence in the values attribute.

Aslo note that the attributeName is required, even for <animateTransform>: the <animateTransform> element can also animate gradientTransform and patternTransform attributes.

The motion of the X-ray goggles, as they scan the image, consists of three components:

• a slow movement up and down,

• a much faster movement side-to-side, and

• rotational movements to angle the goggles first one way, then the other.

None of these animations would be particularly interesting on their own; it is the additive effect that creates the complex motion.

Because none of the durations of the animations are even multiples of the other, the cumulative pattern appears imprecise and more natural. It does not repeat exactly until three and a half minutes have passed (210s, the least common multiple of 10, 3, and 7).

In addition to additive animations, which is one animation element adding on to another, SVG/SMIL defines accumulative animations, where each subsequent repeat of an animation adds on to previous repeats.

The relevant attribute is accumulate and the non-default value is once again sum. (The default value is none.)

This is most useful if you want to create an animation that proceeds in steps, instead of in a single smooth transition. Without accumulation, this would require setting a large list of intermediary values, so you could set discrete transitions or individual easing curves for each setp.

With accumulation, the animation describes the relative change for each step and the number of repeats required to reach the final sum. The calcMode and related attributes describe how each step should progress.

Example 19-X3 gives the code for an accumulative animation increasing the radius of a circle. Each cycle uses keySplines easing to add a pauses, puffing out quickly and then slowing at the end of the repeat. It’s not much to look at in a static screenshot, but you can view the live SVG in a browser with SVG/SMIL support. The appearance is somewhat like a balloon being inflated by a series of big breaths.

<svg xmlns="http://www.w3.org/2000/svg" xml:lang="en"
     viewBox="-80 -80 160 160" width="4in">
    <title>Accumulative Animations</title>
    <circle r="75" fill="crimson">
        <animate attributeName="r"
                 from="0"
                 by="10"
                 calcMode="spline"
                 keyTimes="0;1"
                 keySplines="0.1,1 0.9,0"
                 dur="1s"
                 repeatCount="7.5"
                 accumulate="sum" />
    </circle>
</svg>

Example 19-X3 also demonstrates that repeatCount does not have to be an integer; here, it takes 7.5 repeats to sum up to the desired radius.

¹ SVG Essentials, Second Edition, by J. David Eisenberg and Amelia Bellamy-Royds, has a slightly more comprehensive discussion.