An envelope icon that follows a curved path across a homepage, a dot that travels along a stylised route on a map, a logo that glides along a hand-drawn wave: in every one of these cases, the animated element does not move in a straight line between two points, it follows a precise path. That is exactly what <animateMotion> does, moving an SVG element along a path instead of simply interpolating its x and y coordinates.
Without this element, you would have to recalculate an element’s coordinates by hand, step by step, to make it follow a curve, a calculation that gets tedious fast once the path stops being a straight line. <animateMotion> hands that math over to the browser’s rendering engine, which already knows the exact geometry of the path it is given.
Definition
<animateMotion> is a SMIL animation element that moves its parent element along a path. There are two ways to supply that path: the path attribute, which holds a string of drawing commands in the same format as the d attribute of a <path>, or an mpath sub-element, which references an existing path elsewhere in the document by id, including one placed in an area that is never rendered, such as inside a <defs>. Unlike <animate>, it does not animate a named attribute: it drives the element’s position on the canvas directly.
Main attributes
| Attribute | Role |
|---|---|
path | A string of path commands written directly on the attribute, in the same format as d. |
mpath | A sub-element that references, by id, a path already present elsewhere in the document. |
rotate | auto orients the element in the direction of travel, auto-reverse flips that orientation, a fixed value applies a constant rotation. |
dur | Total duration of the journey, for example 2.5s. |
keyPoints / keyTimes | Control the speed along the path, for instance to slow down through turns. |
repeatCount | Number of repetitions, or indefinite for an endless loop. |
A concrete example
Here is an arrow-shaped icon built from a <polygon>, gliding smoothly along a curve thanks to an <mpath> that references a nearby path.
<svg viewBox="0 0 200 100" xmlns="http://www.w3.org/2000/svg">
<path
id="trajectoire"
d="M10,80 C60,10 140,10 190,80"
fill="none"
stroke="#cbd5e1"
stroke-width="2"
/>
<polygon points="-6,-5 8,0 -6,5" fill="#2563eb">
<animateMotion dur="2.5s" repeatCount="indefinite" rotate="auto">
<mpath href="#trajectoire" />
</animateMotion>
</polygon>
</svg>How it differs from <animateTransform>
It is tempting to confuse <animateMotion> with <animateTransform> set to type="translate", but the two solve different problems. A translation animated with <animateTransform> moves an element in a straight line between a start point and an end point, which is enough for a simple horizontal or vertical slide. <animateMotion>, on the other hand, can follow a curved path, with turns, accelerations and slowdowns defined by the very geometry of the path it is given. For an icon that needs to follow a winding route on a map or ripple like a wave, only <animateMotion> will do.
A classic pitfall
The most common trap is forgetting rotate="auto": without it, the element keeps the exact same orientation for the entire journey, which creates the odd impression of an arrow sliding sideways instead of pointing the way it is heading. A second trap involves the mpath sub-element: the reference must point to a <path> that exists in the document, matched by id and prefixed with a hash, and a simple typo in that id silently breaks the whole animation, with no error message showing up in the console.
rotate="auto", the animated element keeps a fixed orientation from start to finish, even when the path it follows is full of turns.A real use case
An envelope icon that glides along a curve to illustrate a message being sent on a homepage. A dot that travels along a route drawn on a stylised map to visualise a delivery in real time. A small star that follows a wavy path behind a headline to add a bit of life to a marketing page, without reaching for a dedicated JavaScript animation library.
<animateMotion> have to be visible on screen?No, the reference path can perfectly well be defined in an area of the document that is never rendered, for example inside a <defs>, or simply carry a fill="none" attribute and no stroke to stay invisible while still guiding the movement.
<animateMotion> be combined with an extra rotation that is independent of the path?Yes, just add a second <animateTransform> element of type rotate alongside <animateMotion> on the same element: the two animations stack, since they do not drive the same movement mechanism.
path attribute and the mpath sub-element?The path attribute writes the path commands directly on the <animateMotion> element, which is quick for a single, simple path. The mpath sub-element instead references a <path> already present in the document, which avoids duplicating coordinates when several elements need to follow the exact same route.