PathTransition

The PathTransition plugin animates DOM elements along complex vector paths. It supports SVG path curves and coordinate arrays, and features automatic tangential rotation to align elements with the direction of travel.

---

1. SVG Path Following

Path animation requires the provision of an SVG <path> element or coordinate array. The engine computes the necessary path length and coordinates internally.

60 FPS

When autoRotate: true is enabled, the element will automatically rotate to follow the exact curve of the path as it moves.

animate('.airplane', {
  duration: 4,
  pathTransition: {
    path: '#flight-path',
    autoRotate: true,
    alignOrigin: [0.5, 0.5]
  }
})

---

2. Array Waypoints

You can also animate elements in straight lines between specific points by passing an array of {x, y} coordinates.

60 FPS

animate('.dot', {
  duration: 2,
  pathTransition: [
    {x: 0, y: 0},
    {x: 150, y: -50},
    {x: 200, y: 50},
    {x: 0, y: 0}
  ]
})

---

3. Sub-Path Traversal & Cartesian Offsets

You can use the start and end properties to animate along a specific section of the path instead of the whole thing. The offsetX and offsetY properties let you shift the element away from the path by a specific number of pixels, which is great for creating parallel tracks.

60 FPS

---

API Reference

Configuration Object

The pathTransition property accepts a configuration object with the following parameters:

Property	Type	Default	Description
path	string|Element|Array	null	The path to follow. Can be a CSS selector, an SVG <path> element, or an array of {x,y} coordinates.
autoRotate	boolean|number	false	If true, the element rotates to follow the curve of the path. You can also pass a number to add a fixed rotation offset in degrees.
start	number	0	Where the animation should start on the path (from 0.0 to 1.0).
end	number	1	Where the animation should end on the path (from 0.0 to 1.0).
alignOrigin	Array	[0, 0]	Sets the alignment point of the element, similar to CSS transform-origin. [0.5, 0.5] means the center.
offsetX	number	0	Shifts the element horizontally away from the path by a specific number of pixels.
offsetY	number	0	Shifts the element vertically away from the path by a specific number of pixels.

Standalone Class Mode

The PathTransition class provides imperative control mechanisms independent of the Tween factory.

import { PathTransition } from 'animx/plugins/PathTransition'

const motion = PathTransition.create('.car', {
  path: '#racetrack',
  duration: 3,
  autoRotate: true,
  onUpdate: ({ progress, x, y, angle }) => {
    console.log(`x: ${x}, y: ${y}, angle: ${angle}deg`);
  }
})

motion.seek(0.5);