KQ-575 · PATH/RIDER

Path Rider

Something that rides a path. One value between zero and one places the rider at that fraction of the path's length using the browser's own geometry — a point plus the two either side of it, which give the tangent it turns to — and the travelled part of the route draws in behind it from the same value through pathLength, so the line and the rider cannot disagree. Scroll-linked progress is mapped linearly from the container and never sprung, play runs the same value on a linear tween that pauses with the tab and resumes where it stopped, and the rider is hidden from assistive technology while the caption carries the position as text.

KQ-575 · PATH/RIDER

Coldbrook overnight, depot 3 to the yard gate0%

Progress 0%

Install

One command — the source lands in your repo. Or copy it from the Code tab.

$ pnpm dlx shadcn@latest add @kinetiq/path-rider

Props

path: string; default —; SVG path data the rider follows.
viewBox: string; default 0 0 320 180; The coordinate space the path is drawn in.
progress: number; default —; Controlled position along the path, 0–1. Omit to follow the container.
container: React.RefObject<HTMLElement | null>; default —; Scroll-link source; used when progress is omitted.
rider: React.ReactNode; default —; What travels. Defaults to a chevron badge.
playing: boolean; default false; Runs progress to the end on a linear tween.
duration: number; default 4000; Length of a full run, ms.
onProgressChange: (progress: number) => void; default —; Fires with progress, 0–1, whenever the whole percent changes.
onPlayEnd: () => void; default —; Fires when a run reaches the end.
label: string; default Route; Names the route in the caption.

Prop	Type	Default	Description
path	string	—	SVG path data the rider follows.
viewBox	string	0 0 320 180	The coordinate space the path is drawn in.
progress	number	—	Controlled position along the path, 0–1. Omit to follow the container.
container	React.RefObject<HTMLElement \| null>	—	Scroll-link source; used when progress is omitted.
rider	React.ReactNode	—	What travels. Defaults to a chevron badge.
playing	boolean	false	Runs progress to the end on a linear tween.
duration	number	4000	Length of a full run, ms.
onProgressChange	(progress: number) => void	—	Fires with progress, 0–1, whenever the whole percent changes.
onPlayEnd	() => void	—	Fires when a run reaches the end.
label	string	Route	Names the route in the caption.