The TikZ and PGF Packages
Manual for version 3.1.10

This module contains the basic layer support of animations, which is documented in the following.

Adds an animation of the ⟨attribute⟩ of a future object to the current graphic. Attributes are things like the “fill opacity” or the transformation matrix or the line width.

The ⟨options⟩ are keys that configure how the attribute changes over time. Using the entry key multiple times, you specify which value the chosen attribute should have at different points in time. Unless special keys are used, “outside” the specified timeline the animation has no effect:

Other keys, like repeats, allow you to specify how the animation behaves “as a whole”. These keys are documented later in this section.

The Attributes

In detail, the \pgfanimateattribute command opens a TeX-scope, looks up the type values of the specified ⟨attribute⟩ have (if you wish to animate the opacity of an object, the type is “scalar” meaning that entries must be scalar numbers; when you animate the fill attribute, the type is “color” and values must be colors, and so on), and then executes the ⟨options⟩ with the path prefix /pgf/animation. Finally, an appropriate system layer command \pgfsysanimate... is called to create the actual animation and the scope is closed.

The following ⟨attributes⟩ are permissible:

These attributes are detailed in Sections 116.3 to 116.5, but here is a quick overview:

• • draw and fill refer to the color used to draw (stroke) and fill paths in an object, respectively. Typical values for this attribute are red or black!10.

• • line width is, of course, the line width used in an object. Typical values are 0.4pt or 1mm. Note that you (currently) cannot use keys like thin or thick here, but this may change in the future.

• • motion is a slightly special attribute: It allows you to specify a path along which the object should be moved (using the along key). The values given to the entry key for this attribute refer to a fraction of the distance along the path. See the along key for details.

• • opacity and the variants fill opacity and draw opacity animate the opacity of an object. Allowed values range between 0 and 1.

• • path allows you to animate a path (it will morph). The “values” are now paths themselves. See Section 116.4 for details.

• • rotate refers to a rotation of the object. Values for the entry key are the rotation angles like 0 or 90.

• • scale refers to the scaling of the object. Values are either single scalars values (like 1 or 1.5) or two numbers separated by a comma (like 1,1.5 or 0.5,2), referring to the \(x\)-scaling and \(y\)-scaling.

• • softpath is a special case of the path attribute, see Section 116.4 once more.

• • translate shifts the object by a certain vector. Values are points like \pgfpoint{1cm}{2cm}.

• • view allows you to animate the view box of a view, see Section 116.5 for details.

• • visible refers to the visibility of an object. Allowed values are true and false.

• • stage is identical to visible, but when the object is not animated, it will be hidden by default.

• • xskew and yskew skew the object. Attributes are angles like 0 or 45 or even 90.

The Target Object

As stated earlier, the ⟨options⟩ are used to specify the object whose attribute for which an animation should be added to the picture. Indeed, you must specify the object explicitly using the whom key and you must do so before the object is created. Note that, in contrast, in svg you can specify an animation more or less anywhere and then use hyper-references to link the animation to the to-be-animated object; pgf insists that you specify the animation before the object. This is a bit of a bother in some situations, but it is the only way to ensure that pgf has a fighting chance to attach some additional code to the object (which is necessary for almost all animations of the transformation matrix).

As explained in the introduction of this chapter, an “animation” is just a bit of special text in the output document asking a viewer application to animate the object at some later time. The \pgfanimateattribute command inserts this special text immediately, even though it refers to an object created only later on. Normally, this is not a problem, but the special text should be on the same page as the to-be-animated object. To ensure this, it suffices to call \pgfanimateattribute no earlier than the beginning of the pgfpicture containing the object.

Naming the Animation

You can assign a name to an animation for later (or early) reference. In particular, it is possible to begin another animation relative to the beginning or end of this animation and for referencing this animation must be assigned a name. See the of and of next keys for details.

The command works like \pgfanimateattribute, only instead of ⟨options⟩ you specify some ⟨code⟩ whose job is to setup the options.

You use this key repeatedly to specify the different values that the ⟨attribute⟩ should have over time. At the ⟨time⟩ specified, the ⟨attribute⟩ will have the value specified as ⟨value⟩:

You need to call entry once for each time in the timeline for which you want to specify a ⟨value⟩ explicitly. Between these times, the values get interpolated (see below for details). You need to specify the ⟨time⟩s in non-decreasing order (it is permissible and sometimes also necessary to specify the same time twice, namely to create a “jump” of the value of some attribute).

The ⟨time⟩ is parsed using the command \pgfparsetime described later.

Start and end of the timeline. The first and last times of the timeline are a bit special: The timeline starts on the first time and the duration of the timeline is the difference between the first and last time. “Starting” on the start time actually means that any beginnings (see the begin and end keys) get offset by the start time; similarly end times are offset by this value.

Syntax of the values. The syntax of the ⟨value⟩ varies according to the type of the ⟨attribute⟩. In detail, these are:

Interpolation between key times. You use the entry key repeatedly, namely once for each “key time”, which is a time point for which you specify the value of the attribute explicitly. Between these key times, the attribute’s value is interpolated. Normally, this is just a linear interpolation, but you can influence this using the following keys, see Section 26.5.4 for details.

The syntax of the ⟨value⟩ is the same as for the entry key. The ⟨value⟩ is installed as the value of the object’s attribute whenever the timeline is not active. This makes it easy to specify the value of an attribute when the animation is “not running”.

This command works like \pgfmathparse (indeed, it calls is internally), but returns the result in the macro \pgftimeresult rather than \pgfmathresult. Furthermore, the following changes are installed:

• • The postfix operator s is added, which has no effect.

• • The postfix operator ms is added, which divides a number by 1000, so 2ms equals 0.002s.

• • The postfix operator min is added, which multiplies a number by 60.

• • The postfix operator h is added, which multiplies a number by 3600.

• • The infix operator : is redefined, so that it multiplies its first argument by 60 and adds the second. This implies that 1:20 equals 80s and 01:00:00 equals 3600s.

• • The parsing of octal numbers is switched off to allow things like 01:08 for 68s.

When this command is used inside a TeX scope, the behavior of \pgfanimateattribute changes: Instead of adding an animation to the object and the attribute, the object’s attribute is set to value it would have during the animation at time ⟨time⟩. Note that when this command is used in a TeX scope, no animation is created and no support by the driver is needed (so, it works with pdf).

Timing and Events. The timeline of an animation normally starts at a “moment 0s” and the ⟨time⟩ is considered relative to this time. For instance, if a timeline contains, say, the settings entry={2s}{0} and entry={3s}{10} and {⟨time⟩} is set to 2.5s, then the value the attribute will get is 5.

It is, however, also possible to specify that animations begin and end at certain times relative to events like a click event. These events are not relevant with respect to snapshots. However, there is one key that allows you to specify the beginning of the snapshot timeline:

Note that the end keys have no effect with snapshots, that is, with a snapshot all animations always run till the end of the timeline (which may or may not be “forever”).

Limitations. For snapshots, the value an animation has at time ⟨time⟩ must be computed by TeX. While in many cases this is easy to achieve, in some cases this is not trivial such as a timeline for a path with repeats plus smoothing via splines. An additional complication is the fact that an animation may be specified at a place far removed from the actual to-be-animated object. For these reasons, certain limitations apply to snapshots:

• • The begin and begin on keys have no effect (but begin snapshot has one.

• • The end and end on keys have no effect.

• • The current value may not be used in a timeline (since pgf cannot really determine this value).

• • The accumulating specification may not be used with paths, views, or motions.

• • Since the timing computations are done using TeX code, they are not necessarily stable. For instance, when a time interval is very small and there are many repeats or when a spline is very complicated, the calculated values may not be fully accurate.

This command works exactly like \pgfsnapshot only the “moment” that ⟨time⟩ refers to is conceptually \(\meta {time} + \epsilon \): When timeline specifies several values for ⟨time⟩, this command will select the last value at ⟨time⟩, while \pgfsnapshot will select the first value at ⟨time⟩. Similarly, when a timeline ends at ⟨time⟩, \pgfsnapshot will select the last value of the timeline while \pgfsnapshotafter will not apply the animation any more:

You can animate the color of the target object of an animation using the attributes fill or draw, which animate the fill color and the drawing (stroking) color, respectively. To animate both the fill and draw color, you need to create two animations, one for each.

Unlike colors, where there is no joint attribute for filling and stroking, there is a single opacity attribute in addition to the above two attributes. If supported by the driver, it treats the graphic object to which it is applied as a transparency group. In essence, “this attribute does what you want” at least in most situations.

The difference between the visible attribute and an opacity of 0 is that an invisible object cannot be clicked and does not need to be rendered. The (only) two possible values for this attribute are false and true.

This attribute is the same as the visible attribute, only base=false is set by default. This means that the object is only visible when you explicitly during the time the entries are set to true. The idea behind the name “stage” is that the object is normally “off stage” and when you explicitly set the “stage attribute” to true the object “enters” the stage and “leaves” once more when it is no longer “on stage”.

The possible values passed to the entry key are, of course, dimensions.

To specify the dash pattern, you specify a sequence of “on and off” dimensions; see \pgfsetdash for details. Note that you must specify the same number of elements in all patterns of a timeline: You cannot specify that the dash pattern for 1s is {1pt}{2pt} and for 2s is {1pt}{3pt}{2pt} since the number of elements would differ. In particular, you cannot (sensibly) use current value for the first entry since this corresponds to an empty dash pattern (even when you have specified a dash pattern for the target object: this pattern will not be attached to the to-be-animated scope or object but to a surrounding scope and, thus, the to-be-animated scope will not have any dash pattern installed).

You can animate the path itself:

The path is specified by giving path construction commands as in the above example. They will be executed in a special protected scope to ensure that they have only little side effects.

As for the dash pattern, you must ensure that all paths in the timeline have the same structure (same sequence of path construction commands); only the coordinates may differ. In particular, you cannot say that the path at 1s is a rectangle using \pgfpathrectangle and at 2s is a circle using \pgfpathcircle. Instead, you would have to ensure that at both times that path consists of appropriate Bézier curves.

Unlike the dash pattern, the to-be-animated object is, indeed, the path itself and not some special scope. This means that you can use the current value for the start path. However, this also means that you really must pick the path object as the target of the animation. In conjunction with TikZ, this will be an object of type path as in the above example.

When a path is animated, it cannot have “normal” arrows attached to it since due to the way pgf adds arrow tips to paths, these would not “move along” with the path (you get an error message if you try). However, it still is possible to add arrow tips to an animated path, only you need to use the arrows key described next.

Concerning the bounding box computation of the path, a bounding box for all paths mentioned for any time point is used as the overall bounding box.

This key specifies arrow tips during the animation of the path. The syntax for the arrow tips is the same syntax as the \pgfsetarrow command or TikZ’s arrows key. The specified start and end arrow tips are rendered as “markers”, which are added to the path only during the animation. The markers are rotated along with the path in exactly the same way as normal arrow tips would be. To be precise, the rules used for the computation of where arrow tips go and in which direction they head is not always the same for “static” arrow tips (arrow tips added to a normal path) and the “dynamic” arrow tips based on markers; namely when the paths are very short or closed. For this reason, you should add arrow tips to animated paths only when the paths are “nice and simple” in the sense that they consist of a single segment whose ends are reasonably long.

In addition to adding the arrow tips to the path during the animation, the path gets shortened as necessary to compensate for the extend of the arrow tips. However, for this to work, the arrow tips have to be specified before path values are specified (since the shortening is done immediately when a path value is parsed).

Note that the markers that visualize the arrow tips are rendered only once per animation. In consequence, “bending” arrow tips cannot be rendered correctly: As a path “morphs” a bend arrow tip needs not only to rotate along, but must actually “bend along”, which is not supported (neither by pgf nor by svg).

As pointed out earlier, an animated path cannot have “static” arrow tips. However, when you specify a base value, which is the path used whenever there is no active animation, will use the arrow tips. As a result, you can use this to animate a path with an arrow tip:

Just like the normal TikZ key shorten >, this key specifies an extra shortening of to-be-animated paths. Whenever a path is parsed as a value for a path animation, it gets shortened at the end by the ⟨dimension⟩ (and, additionally, by the length of the attached arrow tip). Just like the arrows key, this key must be given before the path entries are specified.

Works like shorten >.

The scale attribute adds an animation of the scaling:

The values passed to the entry key must either be single scalar values or a pair of such numbers separated by a comma (which then refer to the \(x\)- and \(y\)-scaling).

The rotate key adds an animation of the rotation:

The values are scalar values representing a rotation in degrees.

The xskew and yskew keys (and also skew x and skew y, which are aliases) add an animation of the skew (given in degrees, not as a slant):

The values are scalar values.

See xskew.

An alias of xskew.

An alias of yskew.

The translate key adds an animation of the translation (shift):

The values are pgf-points.

Unlike for the previous canvas transformations, for this key the bounding box computation is changed: All points in the to-be-animated scope do not only contribute to the normal bounding box, but they also contribute shifted by all points in the entry list. The effect is that a bounding box is computed that encompasses the animated scope at all stages.

An animation of the canvas transformation is added to all other transformations from surrounding or interior scopes. This means that, in particular, the origin of a canvas transformation is, by default, the origin of the canvas of the scope surrounding the transformation object.

For some canvas animations, like a rotation or a scaling, you will typically wish to use a different origin (like the center of an object that is to be rotated or scaled). You can achieve this effect by surrounding the object by a scope that shifts the canvas to the desired origin, followed by a scope whose transformation matrix you animate, followed by a scope that shifts back the canvas.

The origin key simplifies this process by allowing you to specify the origin of the transformation directly. Internally, however, all this key does is to create the above-mentioned scopes with the necessary shifts.

A second way of changing the canvas transformation matrix is to use the motion attribute:

Just like the translate attribute, this key also changes the bounding box computation.

A view is a canvas transformation that shifts and scales the canvas in such a way that a certain rectangle “matches” another rectangle: The idea is that you “look through” a “window” (the view) and “see” a certain area of the canvas. View animation do not allow you to do anything that cannot also be done using the translate and scale keys in combination, but it often much more natural to animate which area of a graphic you wish to see than to compute and animate a scaling and shift explicitly.

In order to use a view, you first need to create a view, which is done using a {pgfviewboxscope}, see Section 108.3.2, which is used by the views library internally. You can then animate the view using the view attribute. The values passed to the entry key must be two pgf-points, each surrounded by parentheses.

This key specifies when the “moment 0s” should be relative to the moment when the current graphic is first displayed. You can use this key multiple times, in this case the timeline is restarted for each of the times specified (if it is already running, it will be reset). If no begin key is given at all, the effect is the same as if begin=0s had been specified.

It is permissible to set ⟨time⟩ to a negative value.

This key will truncate the timeline so that it ends ⟨time⟩ after the display of the graphic, provided the timeline begins before the specified end time. For instance, if you specify a timeline starting at 2 s and ending at 5 s and you set begin to 1 s and end to 4 s, the timeline will run, relative to the moment when the graphic is displayed from 3 s to 4 s.

When set to true, whenever a timeline ends (either because the last time of timeline has been reached or because an end or end of key have ended it prematurely), the last value the attribute had because of the animation “stays put”. When set to false, which is the initial value, once an animation ends, its effect will be removed “as if it never happened”.

Has the same effect as /tikz/animate/option/begin on, see Section 26.5.2.

Has the same effect as /tikz/animate/option/restart, see Section 26.5.2.

Works exactly like begin on, one possible end of the timeline is specified using the ⟨options⟩.

Use this key to specify that the timeline animation should repeat at the end. The ⟨specification⟩ must consist of two parts, each of which may be empty. The first part is one of the following:

• • Empty, in which case the timeline repeats forever.

  copy
\tikz [very thick] {
\pgfanimateattribute{rotate}{
whom = node, begin on = {click}, repeats,
entry = {0s}{0}, entry = {2s}{90} }
\node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }


• • A ⟨number⟩ (like 2 or 3.25), in which case the timeline repeats ⟨number⟩ times.

  copy
\tikz [very thick] {
\pgfanimateattribute{rotate}{
whom = node, begin on = {click}, repeats = 1.75,
entry = {0s}{0}, entry = {2s}{90} }
\node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }


• • The text “for ⟨time⟩” (like for 2s or for 300ms), in which case the timeline repeats however often necessary so that it stops exactly after ⟨time⟩.

  copy
\tikz [very thick] {
\pgfanimateattribute{rotate}{
whom = node, begin on = {click}, repeats = for 3.5s,
entry = {0s}{0}, entry = {2s}{90} }
\node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }


The second part of the specification must be one of the following:

• • Empty, in which case each time the timeline is restarted, the attribute’s value undergoes the same series of values it did previously.

• • The text accumulating. This has the effect that each time the timeline is restarted, the attribute values specified by the timeline are added to the value from the previous iteration(s). A typical example is an animation that shifts a scope by, say, 1 cm over a time of 1 s. Now, if you repeat this five times, normally the scope will shift 1 cm for 1 s then “jump back”, shift again, jump back, and so on for five times. In contrast, when the repeats are accumulating, the scope will move by 5 cm over 5 s in total.

  copy
\tikz [very thick] {
\pgfanimateattribute{rotate}{
whom = node, begin on = {click}, repeats = accumulating,
entry = {0s}{0}, entry = {2s}{90} }
\node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }


  copy
\tikz [very thick] {
\pgfanimateattribute{rotate}{
whom = node, begin on = {click}, repeats = 2 accumulating,
entry = {0s}{0}, entry = {2s}{90} }
\node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }


This is an alias for repeats.