Skip to content

Live status (tracker mode)

A diagram usually explains a process. In tracker mode, it shows where something real is right now: an order on its way, a food delivery, a support ticket, a job application, a paperwork process. Your site already knows the status; Fluxygram turns it into an animated picture your customers understand at a glance.

You draw the process once, as a normal flow diagram. Then, on each page, you tell the component which block is the current stage:

<script type="module" src="https://cdn.jsdelivr.net/npm/fluxygram@0.3"></script>
<fluxy-gram src="order.flux.json" mode="tracker" stage="shipped"></fluxy-gram>

That’s all. When the stage changes, you change the attribute and the diagram animates to the new stage by itself.

Part of the diagram How it looks
Stages already done Green, with a check
The current stage Depends on status (below), and a particle travels into it
Stages still ahead Dimmed: the whole path is visible, but what’s done stands out
Step bar, autoplay Hidden: a tracker shows the status, nothing else

The current stage’s status says how it’s going:

status Meaning Use it for
pending (default) In progress Most of the time
success Done (green) The last stage, when the process ends
warning Needs attention (amber) A delay, waiting for the customer
error Something went wrong (red) A declined payment, a rejected application

Any of these animate the diagram:

const tracker = document.querySelector('fluxy-gram');
tracker.stage = 'out'; // property
tracker.setAttribute('stage', 'out'); // attribute
tracker.setStage('out', 'warning'); // stage and status in one animation
tracker.setStage('delivered', 'success'); // the end

Prefer setStage() when both change: setting stage and status separately also works (they are batched), but setStage() says what you mean.

Every change fires fluxy-stage, handy for updating text next to the diagram:

tracker.addEventListener('fluxy-stage', (e) => {
const { stage, status, history } = e.detail;
document.querySelector('#eta').hidden = stage === 'delivered';
});
  1. Use a flow, one block per stage, connected in the order things happen. Add kind: "start" and kind: "end" to the first and last blocks.

  2. Use your system’s status values as ids. If your database says shipped, the block id is shipped. The ids are the contract between your app and the diagram; labels can change, be reworded or translated freely.

  3. Write labels for the customer, not for your team: “On the way” instead of “OUT_FOR_DELIVERY”. A description adds a short second line (“you get a full refund”).

  4. Give each failure its own block, connected from the stage where it can happen: received → declined. Then stage="declined" status="error" turns that branch red.

  5. Add steps only if you also want the diagram to explain the process elsewhere: tracker mode ignores them, so the same file can do both.

{
"type": "flow",
"title": "Your order",
"nodes": [
{ "id": "received", "label": "Order placed", "kind": "start", "icon": "cart" },
{ "id": "paid", "label": "Payment confirmed", "icon": "card" },
{ "id": "declined", "label": "Payment declined", "description": "try another card", "icon": "alert" },
{ "id": "shipped", "label": "Shipped", "icon": "truck" },
{ "id": "delivered", "label": "Delivered", "kind": "end", "icon": "home" }
],
"edges": [
{ "from": "received", "to": "paid" },
{ "from": "received", "to": "declined" },
{ "from": "paid", "to": "shipped" },
{ "from": "shipped", "to": "delivered" }
]
}

By default, Fluxygram works out what’s done by following the connections backwards from the current stage. That’s perfect for a straight line with failure branches, and you only need stage.

It can’t guess in two cases:

  • Paths that join. In a job application, Not selected can come after Résumé review or after the Interview. Following connections backwards, both look done.
  • Loops. A support ticket goes Working on it → Waiting for your reply → Working on it again.

For those, pass the stages it actually went through, in order, in history. Only those turn green, and only the connections between consecutive stages:

<fluxy-gram src="application.flux.json" mode="tracker"
stage="rejected" status="error"
history="applied,screening,interview,rejected"></fluxy-gram>
tracker.history = ['open', 'assigned', 'working', 'waiting', 'working'];
tracker.setStage('working');

Most systems already store this (an order’s status log, a ticket’s timeline). The current stage can be the last item of history or not: both work.

Fluxygram doesn’t fetch anything by itself: your page decides where the status comes from. Three common ways, from simplest to most live:

Your server already knows the order when it builds the page. Write the stage in the HTML and you’re done; the customer sees the latest status every time they open it.

// React, Next.js, Remix, Astro…
<fluxy-gram src="/order.flux.json" mode="tracker" stage={order.status} />
<fluxy-gram src="/order.flux.json" mode="tracker" stage="<?= htmlspecialchars($order->status) ?>"></fluxy-gram>

For a page that stays open (a delivery on its way), ask your API for the status every 30 seconds or so. If nothing changed, nothing animates.

const tracker = document.querySelector('fluxy-gram');
async function refresh() {
const res = await fetch(`/api/orders/${orderId}`);
const order = await res.json();
tracker.setStage(order.status, order.status === 'delivered' ? 'success' : 'pending');
}
refresh();
setInterval(refresh, 30_000);

If your backend can push events (Server-Sent Events, WebSockets, Firebase, Supabase Realtime, Pusher…), call setStage() when one arrives:

const events = new EventSource(`/api/orders/${orderId}/events`);
events.onmessage = (e) => {
const { status, history } = JSON.parse(e.data);
tracker.history = history;
tracker.setStage(status);
};

Map them in one place. It’s also where you decide which status means a delay or a problem:

const STAGES = {
PENDING_PAYMENT: ['received', 'pending'],
PAYMENT_FAILED: ['declined', 'error'],
PICKING: ['packed', 'pending'],
CARRIER_DELAYED: ['shipped', 'warning'],
DELIVERED: ['delivered', 'success'],
};
const [stage, status] = STAGES[order.state] ?? [undefined, 'pending'];
if (stage) tracker.setStage(stage, status);

caption shows a short line under the diagram, for what the picture can’t say: a date, a tracking number, what to do next.

<fluxy-gram src="order.flux.json" mode="tracker" stage="out" caption="Arrives today before 6 pm"></fluxy-gram>

Change it like any attribute: tracker.setAttribute('caption', 'Delayed by the carrier: arrives tomorrow').

Keep the same ids in every language and translate only the labels: one file per language (order.en.flux.json, order.es.flux.json), and pick the file by the customer’s language. Your code keeps sending the same stage values. Set lang so the component’s own texts match too.

<fluxy-gram src="/order.es.flux.json" lang="es" mode="tracker" stage="shipped"></fluxy-gram>

Each <fluxy-gram> is independent: a list of orders can show one tracker per order, all using the same src. The file is loaded once per element; it’s small and the browser caches it.

<fluxy-gram src="/order.flux.json" mode="tracker" stage="paid"></fluxy-gram>
<fluxy-gram src="/order.flux.json" mode="tracker" stage="delivered" status="success"></fluxy-gram>

Anything with stages a person waits on:

  • Stores: order, return, refund, repair, custom-made product.
  • Delivery: food, groceries, parcels, moving.
  • Services: support tickets, insurance claims, warranty, car service.
  • Paperwork: visa, license, loan, bank account opening, enrollment.
  • People: job applications, onboarding, patient visits (“triage → doctor → results”).
  • Teams: a deploy, a content approval, a purchase request.

What if stage is a block that doesn’t exist? The diagram shows neutral, as if the process hadn’t started. It never breaks; check the id if you expected otherwise.

Does it need an account or a server? No. Tracker mode runs entirely in the page, from the free, open-source component. Fluxygram Cloud will add hosted trackers that update themselves from your backend, with a shareable link per order.

Can I go back to an earlier stage? Yes, set it. Without history, everything before it turns green again; with history, it shows exactly the path you pass.

Can people still click and zoom? Yes: dragging, zooming and clicking a block work as in any diagram.

Is the logic available outside the browser? Yes: @fluxygram/core exports trackerState(layout, stage, status, history), which returns which blocks are done, current and dimmed. Useful for tests or your own renderer.