offset-distance

Avatar of Geoff Graham
Geoff Graham on (Updated on )

This property began life as motion-offset. This, and all other related motion-* properties, are being renamed offset-* in the spec. We’re changing the names here in the almanac. If you want to use it right now, probably best to use both syntaxes.

The motion-offset property in CSS says: how far along the motion-path are you? This is the animatable property associated with motion paths.

.thing-that-moves {
  /* "Old" syntax. Available in Blink browsers as of ~October 2015 */
  motion-path: path('M 5 5 m -4, 0 a 4,4 0 1,0 8,0 a 4,4 0 1,0 -8,0');
  motion-offset: 0%;

  /* Currently spec'd syntax. Should be in stable Chrome as of ~December 2016 */
  offset-path: path('M 5 5 m -4, 0 a 4,4 0 1,0 8,0 a 4,4 0 1,0 -8,0');
  offset-distance: 0%;
 
  animation: move 3s linear infinite;
}

/* Animate the element along the path from 0% to 100%  */
@keyframes move {
  100% { 
    motion-offset: 100%; /* Old */
    offset-distance: 100%; /* New */
  }
}

In the example above, we have set the initial motion-offset value at 0%, though it’s worth noting that zero is the default value, even when not explicitly defined (we could have left that out).

Variables

The offset-distance property accepts the following values:

  • length
  • percentage

In both cases, the value is specifying the length of distance from the starting point of the path (default is 0px or 0%) to the end point of the path.

Example

In this example, we have two circles where one small circle travels along the path of a larger circle.

Here is the SVG file we are using to draw the shapes:

<svg viewbox="0,0 10,10" width="200px" height="200px">
  
  <!-- the circle path to be animated along -->  
  <path 
    class="track"
    fill="none"
    stroke-width="0.25"
    d="M 5 5 m -4, 0 a 4,4 0 1,0 8,0 a 4,4 0 1,0 -8,0"
  />
  
  <!-- the mover that follows the path -->
  <circle class="marker" r="1" fill="orange"></circle>
  
</svg>

Now, we can set the .marker class in our CSS to follow the .track class coordinates:

/* The motion-offset is zero by default */
.marker {
  offset-path: path('M 5 5 m -4, 0 a 4,4 0 1,0 8,0 a 4,4 0 1,0 -8,0');
  animation: move 3s linear infinite;
}

@keyframes move {
  /* Move the .marker from it's default value of 0% to 100% of the path's length */
  100% { offset-distance: 100%; }
}

See the Pen Simple Example of Animating Along a Path by Geoff Graham (@geoffgraham) on CodePen.

Similarly, we can stop the offset-distance value at 50% and the animation would drop off halfway around the path:

See the Pen Simple Example of Animating Along a Path by Geoff Graham (@geoffgraham) on CodePen.

Or, to control the speed of the animation, we could multiply the offset-distance value to 300% to speed things up. However, if we’ve specified the amount of time the animation runs at a value greater than what it takes the element to travel the path, then the movement will stop until the animation has completed its interval before repeating:

See the Pen Simple Example of Animating Along a Path by Geoff Graham (@geoffgraham) on CodePen.

Browser support

the offset-distance property is still considered an experimental feature at the time of this writing and there is no documentation on browser support. However, there is documentation on motion-path support and we can use that as a baseline for the time being.

This browser support data is from Caniuse, which has more detail. A number indicates that browser supports the feature at that version and up.

Desktop

ChromeFirefoxIEEdgeSafari
4672No7916.0

Mobile / Tablet

Android ChromeAndroid FirefoxAndroidiOS Safari
12212312216.0

Related Properties

Additional Information