Trace UI · Open source

The journey,
beautifully clear.

A shipment timeline for the experience after checkout. Make every scan readable, every exception visible, and every uncertain update honest.

Build your timelineGet the starterStart in five minutes
MIT licensedReact 18 / 19Any tracking providerNo account for the demo4 interface languages · RTL

Built for real-world tracking data: carrier exceptions, customs scans, cached results, and local times without a timezone.

The component makes no requests and includes no telemetry. Bring your own data, or connect Trace on your server.

Local samples · No API calls

Example carrier

Shipment journey

DEMO-1042

Delivered

Demo data · This is an illustrative shipment, not a live tracking result.

  1. Label created
  2. On the way
  3. Out for delivery
  4. Delivered

Scan history

4 events

  1. Delivered to the recipient

    Latest reported event

    Example destination

  2. Out for delivery

    Example delivery depot

  3. Arrived at the sorting facility

    Example sorting hub

  4. Shipping label created

    Example origin

Local exampleEvents in supplied order · Times shown in UTC

Illustrative scenarios, including stale and unavailable states. No real parcel or estimated delivery is represented.

A running app, right away

From clone to timeline.

Install the starter with Node 22+ and open localhost:3000. Local scenarios work immediately. The five-minute target covers the local demo; account verification and optional webhook setup take additional steps.

  1. 01 · Try the component. Switch states and themes without making API calls.
  2. 02 · Connect the sandbox. Add your key on the server and use a separate private-preview password.
  3. 03 · Use your own data. Map any provider, or connect a real shipment through Trace.
Terminal · local demo
git clone https://github.com/traceapi-dev/trace-ui.git
cd trace-ui
npm ci
npm run dev

# Open http://localhost:3000
# No API key or database needed for the demo.

Drop it into your app.

Use the complete timeline or compose summary, progress, history, freshness and exception primitives. Add split-order views, choose comfortable or compact density, and localize the interface into English, Spanish, French or Arabic. There is no Tailwind dependency or required Trace branding. The pinned download works while registry publication is being prepared.

React · your own provider
npm install https://traceapi.dev/downloads/traceapi-timeline-0.2.0.tgz

import { ShipmentTimeline } from "@traceapi/timeline";
import "@traceapi/timeline/styles.css";

<ShipmentTimeline shipment={yourShipment} theme="light" />

Signed updates, saved first.

The Next.js example includes a webhook receiver that verifies the raw body, persists it in a Postgres inbox, and deduplicates replayed events. Storage failure stays retryable. It does not send customer notifications or perform order actions.

Read the starter guideWebhook API docs
The live preview is private by default. Keep keys server-side and add your own merchant/order authorization before creating a public tracking portal.