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.
The idea in 30 seconds
Section titled “The idea in 30 seconds”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.
What the customer sees
Section titled “What the customer sees”| 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 |
Changing the stage
Section titled “Changing the stage”Any of these animate the diagram:
const tracker = document.querySelector('fluxy-gram');
tracker.stage = 'out'; // propertytracker.setAttribute('stage', 'out'); // attributetracker.setStage('out', 'warning'); // stage and status in one animationtracker.setStage('delivered', 'success'); // the endPrefer 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';});Designing the diagram
Section titled “Designing the diagram”-
Use a
flow, one block per stage, connected in the order things happen. Addkind: "start"andkind: "end"to the first and last blocks. -
Use your system’s status values as ids. If your database says
shipped, the block id isshipped. The ids are the contract between your app and the diagram; labels can change, be reworded or translated freely. -
Write labels for the customer, not for your team: “On the way” instead of “OUT_FOR_DELIVERY”. A
descriptionadds a short second line (“you get a full refund”). -
Give each failure its own block, connected from the stage where it can happen:
received → declined. Thenstage="declined" status="error"turns that branch red. -
Add
stepsonly 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" } ]}Branches and loops: history
Section titled “Branches and loops: history”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.
Connecting it to your data
Section titled “Connecting it to your data”Fluxygram doesn’t fetch anything by itself: your page decides where the status comes from. Three common ways, from simplest to most live:
1. Rendered with the page
Section titled “1. Rendered with the page”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>2. Checking every so often
Section titled “2. Checking every so often”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);3. Pushed in real time
Section titled “3. Pushed in real time”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);};Your statuses don’t match the blocks?
Section titled “Your statuses don’t match the blocks?”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);A sentence under the diagram
Section titled “A sentence under the diagram”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').
Translations
Section titled “Translations”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>Several on one page
Section titled “Several on one page”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.
Questions
Section titled “Questions”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.