CSS offset-distance Property

The offset-distance property sets the position of an element along a predefined motion path.

selector { offset-distance: <length> | <percentage>; }
<length> Specifies a fixed distance along the path using standard units like px, em, or rem.
<percentage> Specifies the position as a percentage of the total length of the path.

Code Examples

A basic example showing a red square positioned exactly halfway along a diagonal path.

<div class="track">
  <div class="runner"></div>
</div>
<style>
.track {
  width: 300px;
  height: 300px;
  border: 2px dashed #cccccc;
  margin: 50px;
}
.runner {
  width: 40px;
  height: 40px;
  background: #ff0000;
  offset-path: path("M 0 0 L 300 300");
  offset-distance: 50%;
}
</style>

An advanced example using JavaScript to link a range slider to the offset-distance of an element on a curved path.

<div id="race-car"></div>
<input type="range" min="0" max="100" value="0" id="throttle">

<style>
#race-car {
  width: 50px;
  height: 30px;
  background: #0000ff;
  offset-path: path("M 50 50 Q 250 50 250 250 T 450 250");
  offset-rotate: auto;
}
</style>

<script>
const car = document.getElementById("race-car");
const slider = document.getElementById("throttle");

slider.addEventListener("input", (e) => {
  car.style.offsetDistance = e.target.value + "%";
});
</script>

Pro Tip

You can use values greater than 100% or less than 0%. While this usually leaves the element at the end or beginning of the path, for certain closed shapes or specific path definitions, it can create interesting looping or clamping effects.

Deep Dive

Think of the offset-path property as a set of railroad tracks you have laid down on your page. The offset-distance property is the throttle that tells the train exactly where to stop along those tracks. If you set the distance to 0%, the element sits at the very start of the path. If you set it to 100%, it sits at the very end. By animating this value from 0% to 100% using CSS keyframes, you can make an element travel along complex curves, circles, or polygons that would be a nightmare to calculate using standard top, left, or transform coordinates. It calculates the distance based on the total length of the path shape or SVG string provided in the offset-path property.

Best Practices

Use percentage values for most scenarios because they ensure the element travels the full length of the path regardless of how long or short that path is. If you use fixed pixel lengths and then change your path shape later, your element might stop short or try to travel past the end of the line.

Common Pitfalls

The most common mistake is trying to use offset-distance without defining an offset-path first. If there are no tracks, the train has nowhere to go. Also, remember that the element's rotation will follow the path's curve by default unless you override it with the offset-rotate property.

Accessibility

Constant motion can be a major problem for users with vestibular disorders or motion sensitivity. Always wrap your motion-path animations in a prefers-reduced-motion media query to ensure that users who have requested less movement see a static, accessible version of your interface.

Dev Data Table: offset-distance property

default 0
animatable yes
inherited no
experimental no
year_intro 2015
year_standard 2020
js_syntax_1 element.style.offsetDistance = "50%";
js_syntax_2 element.style.setProperty("offset-distance", "50%");
js_note When manipulating this via JavaScript, ensure the value includes the unit like px or percent as a string.
browsers { "Chrome": 55, "Edge": 79, "Firefox": 72, "Safari": 15.4, "Opera": 42, "Chrome Android": 55, "Safari on iOS": 15.4, "Samsung Internet": 6, "Opera Mobile": 42 }
results render here...