KQ-1334 · ORDER/TRACKER

Order Tracker

An order tracking surface where one progress value drives everything: the live dot rides the shipment's path between stages on glide as `now` advances, the path fills behind it through a sweeping clip, and on the map strip the van rides its route while the strip pans to keep it centred; reaching the door lands a check on recoil. Grab the dot and it scrubs the history 1:1 — fill, van and a time chip rewinding with it, ticking at every scan — then settles on the nearest scan with the release velocity, while the delivery window rolls digit by digit on snap and Change opens a measured disclosure on glide. The path is a slider: arrow keys step through the scans, Home goes to the first, End and Escape come back to now.

KQ-1334 · ORDER/TRACKER

Track order

Out for delivery

Fernworks Home · FW-20417 · 4 items

Fieldline Freight FLF 4471 0926 3318

Arriving

Scans

Thu, Oct 1
Wed, Sep 30
Tue, Sep 29

In this parcel

Stoneware pour-over setClay · 1 × $64.00$64.00
Basin kettle, 1 lSlate · 1 × $89.00$89.00
Paper filters, 100Unbleached · 2 × $8.50$17.00

Subtotal: $170.00
Shipping: Free
Tax: $13.60
Total: $183.60

14 Larch Row, Coldbrook

out for delivery · window 2:40 pm–4:10 pm

Open it on the Studio stage

Install

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

$ pnpm dlx shadcn@latest add @kinetiq/order-tracker

Props

path: "rail" | "road" | "arc"; default "road"; The progress track's shape: a straight rail, a winding road whose bends the stages ride, or one long arc.
eta: "window" | "countdown" | "day"; default "window"; How the arrival reads: the delivery window, a countdown to it that rolls as `now` advances, or the weekday.
map: "streets" | "dots" | "none"; default "streets"; The map strip: seeded streets, blocks, a river and parks; a dot grid with the route only; or no strip.
order: OrderTrackerOrder; default defaultOrderTrackerOrder; The order's number, store, carrier and tracking number, the map's origin, waypoint and destination labels, and the full address.
stages: OrderStage[]; default defaultOrderStages; The shipment's stages in order: label, when it was reached (or is expected), whether it has been reached, where, and where along the map's route it happens.
scans: OrderScan[]; default defaultOrderScans; Every carrier scan: time, text, the stage it belongs to, place, and a warn tone for hold-ups. Past scans are the marks the dot can stop on.
items: OrderItem[]; default defaultOrderItems; What is in the parcel: name, variant, quantity, unit price, a pigment and a thumbnail kind.
shipping: number; default 0; Shipping charged; 0 reads Free.
tax: number; default —; Tax charged. Defaults to 8% of the items.
now: number | Date; default defaultOrderTrackerNow; The tracker's moment: where the dot sits between stages and what the countdown reads. Never read from the clock during render.
delivery / defaultDelivery: OrderWindow; default —; The delivery window (start and end, ms). Controlled or uncontrolled; defaults to the first of windows.
onDeliveryChange: (window: OrderWindow) => void; default —; Fires from the choice in Change with the new window. A controlled host that refuses it keeps the readout where it was.
windows: OrderWindow[]; default defaultOrderWindows; Windows the visitor may move delivery to. Empty hides Change.
onHelp: () => void; default —; Get help was pressed. Without it there is no Get help button.
onScanSelect: (scanId: string | null) => void; default —; A scan was previewed by drag, key or list (its id), or the preview went back to now (null).
format: (amount: number) => string; default —; Money. Defaults to Intl currency formatting in locale and currency.
formatTime: (ms: number) => string; default —; Times. Defaults to a 12-hour UTC clock, "2:40 PM", so server and browser agree.
formatDate: (ms: number) => string; default —; Dates. Defaults to "Thu, Oct 1" in UTC.
formatDay: (ms: number) => string; default —; The weekday the day view shows large. Defaults to "Thursday" in UTC.
locale: string; default "en-US"; Locale for the default money format.
currency: string; default "USD"; Currency for the default money format.
status: "ready" | "loading" | "error"; default "ready"; Whether tracking has arrived: a skeleton while loading, a message and Try again on error.
onRetry: () => void; default —; Try again was pressed after tracking failed to load.
title: string; default "Track order"; The surface's heading.
label: string; default —; The region's accessible name. Defaults to the title.
sound: boolean; default false; Ticks for each scan crossed while scrubbing or stepped with a key, a plip as the dot lands back at now, as a window is chosen and as the tracking number is copied. Nothing sounds on its own.
disabled: boolean; default false; Read only: the history cannot be scrubbed, the map not panned, the window not changed.
className: string; default —; Classes for the root, which is at most 560px tall and scrolls inside itself.

Prop	Type	Default	Description
path	"rail" \| "road" \| "arc"	"road"	The progress track's shape: a straight rail, a winding road whose bends the stages ride, or one long arc.
eta	"window" \| "countdown" \| "day"	"window"	How the arrival reads: the delivery window, a countdown to it that rolls as `now` advances, or the weekday.
map	"streets" \| "dots" \| "none"	"streets"	The map strip: seeded streets, blocks, a river and parks; a dot grid with the route only; or no strip.
order	OrderTrackerOrder	defaultOrderTrackerOrder	The order's number, store, carrier and tracking number, the map's origin, waypoint and destination labels, and the full address.
stages	OrderStage[]	defaultOrderStages	The shipment's stages in order: label, when it was reached (or is expected), whether it has been reached, where, and where along the map's route it happens.
scans	OrderScan[]	defaultOrderScans	Every carrier scan: time, text, the stage it belongs to, place, and a warn tone for hold-ups. Past scans are the marks the dot can stop on.
items	OrderItem[]	defaultOrderItems	What is in the parcel: name, variant, quantity, unit price, a pigment and a thumbnail kind.
shipping	number	0	Shipping charged; 0 reads Free.
tax	number	—	Tax charged. Defaults to 8% of the items.
now	number \| Date	defaultOrderTrackerNow	The tracker's moment: where the dot sits between stages and what the countdown reads. Never read from the clock during render.
delivery / defaultDelivery	OrderWindow	—	The delivery window (start and end, ms). Controlled or uncontrolled; defaults to the first of windows.
onDeliveryChange	(window: OrderWindow) => void	—	Fires from the choice in Change with the new window. A controlled host that refuses it keeps the readout where it was.
windows	OrderWindow[]	defaultOrderWindows	Windows the visitor may move delivery to. Empty hides Change.
onHelp	() => void	—	Get help was pressed. Without it there is no Get help button.
onScanSelect	(scanId: string \| null) => void	—	A scan was previewed by drag, key or list (its id), or the preview went back to now (null).
format	(amount: number) => string	—	Money. Defaults to Intl currency formatting in locale and currency.
formatTime	(ms: number) => string	—	Times. Defaults to a 12-hour UTC clock, "2:40 PM", so server and browser agree.
formatDate	(ms: number) => string	—	Dates. Defaults to "Thu, Oct 1" in UTC.
formatDay	(ms: number) => string	—	The weekday the day view shows large. Defaults to "Thursday" in UTC.
locale	string	"en-US"	Locale for the default money format.
currency	string	"USD"	Currency for the default money format.
status	"ready" \| "loading" \| "error"	"ready"	Whether tracking has arrived: a skeleton while loading, a message and Try again on error.
onRetry	() => void	—	Try again was pressed after tracking failed to load.
title	string	"Track order"	The surface's heading.
label	string	—	The region's accessible name. Defaults to the title.
sound	boolean	false	Ticks for each scan crossed while scrubbing or stepped with a key, a plip as the dot lands back at now, as a window is chosen and as the tracking number is copied. Nothing sounds on its own.
disabled	boolean	false	Read only: the history cannot be scrubbed, the map not panned, the window not changed.
className	string	—	Classes for the root, which is at most 560px tall and scrolls inside itself.