Scroll Path Journey

Quick Start

1. Add the stylesheet to your HTML <head>:

Code snippet omitted: it ships with the download.

2. Add GSAP and the required plugins before </body>:

Code snippet omitted: it ships with the download.

3. Add a journey container to your page body:

Code snippet omitted: it ships with the download.

The motion path, progress path, and shadow path must use the same d value. The script measures the progress path, aligns the marker to the motion path, and synchronizes both with the container's scroll range.

Using It With Your Own Design

What the script needs from your markup: the data-* hooks in the table below, and nothing else. .journey-stage is the one class it reads (it is the element the ResizeObserver watches, so it should be the box the SVG sizes). Every other class in the demo (.journey-bar, .journey-head, .checkpoint, .checkpoint-pin, .checkpoint-media, the --pin-x custom properties) is the demo's own styling and can be replaced.

How the demo lays the route out. The container is a normal block in the page flow, not a pinned scene: the SVG is display: block; width: 100%; height: auto, so its viewBox sets the stage's height and the page is as tall as the route. With data-journey-start="top top" and data-journey-end="bottom bottom" the marker leaves the start of the path as the container reaches the top of the viewport and arrives at the end as the container's bottom does. Anything inside the container above or below the stage (the demo's head and foot) is part of that scroll range, which is why the demo puts them inside [data-path-journey]: the route starts moving on the first pixel of scroll, with no dead intro.

Placing checkpoints on the route. Because the stage scales uniformly with its width, a checkpoint positioned in percentages of the stage lands on the same route coordinate at every size. The demo sets left/top from --pin-x/--pin-y (route coordinate divided by the viewBox size) and offsets the entry to one side with a transform, so the pin sits exactly where the marker will pass. Work those coordinates out once with MotionPathPlugin.getPositionOnPath() for each data-progress value; the two route geometries usually put the same stop at different fractions of their length, which is what data-progress-mobile is for.

Start states the demo's CSS owns. The walked stroke (.route-progress) is opacity: 0 until the has-js class exists, so a page without JavaScript shows the dotted route rather than a fully drawn red one; the marker is display: none under the same gate because it sits at the SVG origin until the script places it. Upcoming checkpoints are greyed and dimmed only under .has-js and only while they carry neither is-active nor is-passed, so every camp is shown in full without JavaScript and under prefers-reduced-motion. Keep those three gates if you restyle: an ungated opacity: 0 ships a blank route to no-JS visitors.

The marker. The script sets x, y, rotation and scale on [data-journey-marker] and clears them on destroy. Give it position: absolute; top: 0; left: 0 and a fixed width and height; anything inside it (the demo's nose) is yours. data-journey-rotate="false" if your marker has no direction.

Required Structure

Element	Purpose
[data-path-journey]	Root scroll container and ScrollTrigger target
.journey-stage	Stable visual stage observed for responsive rebuilds
[data-journey-path="desktop"]	Invisible desktop path used by MotionPathPlugin
[data-journey-progress="desktop"]	Visible desktop stroke drawn with scroll progress
[data-journey-path="mobile"]	Mobile path used below 761px
[data-journey-progress="mobile"]	Visible mobile progress stroke
[data-journey-marker]	HTML or SVG element aligned to the active route
[data-journey-checkpoint]	Clickable milestone with a data-progress value (and optional data-progress-desktop / data-progress-mobile)

You may omit the mobile route if the desktop geometry works at every size, but the supplied script expects matching desktop and mobile paths. Duplicating the same path under both selectors is valid.

Options

All journey options go on the [data-path-journey] element.

Attribute	Values	Default	Description
data-journey-scrub	true, false, number	0.8	ScrollTrigger scrub behavior. A number is smoothing time in seconds
data-journey-lead	0 to 0.5	0	How far the drawn progress stroke runs ahead of the marker, as a fraction of the route. The demo uses 0.05
data-journey-swell	0 to 1	0.3	How much the marker scales up at full scroll speed before settling back with an elastic ease. 0 disables the velocity response
data-journey-start	ScrollTrigger position	top top	Scroll position where route movement begins
data-journey-end	ScrollTrigger position	bottom bottom	Scroll position where route movement completes
data-journey-rotate	true, false	true	Rotate the marker to match the path tangent
data-journey-active-class	CSS class name	is-active	Class applied to the current checkpoint

Checkpoint option:

Attribute	Values	Description
data-progress	Number from 0 to 1	Route position where the checkpoint becomes current
data-progress-desktop, data-progress-mobile	Number from 0 to 1	Per-route override of data-progress for that breakpoint, for when the desktop and mobile geometries reach the same stop at different fractions of their length

Keep checkpoint values in ascending order. The script sorts them internally (per active route), but matching DOM and route order makes the markup easier to maintain.

Responsive Paths

MotionPathPlugin calculates path alignment when the tween initializes. Changing the SVG's rendered dimensions later does not automatically realign the marker. This effect handles that in two ways:

1. gsap.matchMedia() selects separate desktop and mobile paths at 761px.
2. A debounced ResizeObserver rebuilds the tween when the stage changes size, preserving the current ScrollTrigger progress.

Use the same SVG viewBox for the motion, progress, and shadow paths within each breakpoint. The desktop and mobile viewBoxes may differ from one another (the demo uses 0 0 1000 2200 and 0 0 380 1500), and each checkpoint can carry its own data-progress-desktop / data-progress-mobile value so it activates where the marker actually passes it on each route.

Checkpoint Navigation

Checkpoint elements are buttons in the supplied demo. Activating one calculates its document scroll position from the ScrollTrigger start/end values and scrolls directly to that point on the route.

Code snippet omitted: it ships with the download.

The current checkpoint receives aria-current="step" and the configured active class. Earlier checkpoints receive is-passed.

Accessibility

• Checkpoints use native buttons and are available to keyboard and assistive-technology users.
• The active checkpoint receives aria-current="step".
• An optional [data-journey-status] live region announces checkpoint changes without reporting every percentage update.
• Decorative route SVGs use aria-hidden="true". Give meaningful SVG diagrams role="img" and an accessible name instead.
• prefers-reduced-motion: reduce hides the moving marker, draws the full route, and presents every checkpoint developed and readable; the velocity swell and the pin ring animation are off.
• Content is never hidden behind animation initialization, so the journey remains readable if JavaScript fails.

Styling Your Own Marker

The marker can contain any HTML or inline SVG. Keep its width and height stable so MotionPathPlugin aligns its center consistently.

Code snippet omitted: it ships with the download.

Code snippet omitted: it ships with the download.

Do not position the marker with margins, and leave transform to the script (it composes translate, rotation and the velocity scale). Use alignOrigin in assets/script.js if the visual center is not the element's geometric center.

Browser Support

Modern evergreen browsers with SVG and ES6 support. ResizeObserver is used when available; the journey still works without it but will only rebuild when the media query changes or window.ScrollPathJourney.refresh() is called.

Dependencies

Required:

• GSAP 3.12+
• ScrollTrigger
• MotionPathPlugin

Optional:

• Lenis or another smooth-scroll library. The effect does not initialize one and works with native scrolling by default.