Skip to content
Browse documentation

Your environments down a rail, each with the version it runs: promote one and a copy rides down to the next station, waits while it deploys, then docks.

Used forDeploy and CI dashboardsRelease managersFeature and model rolloutsInternal admin tools

Install with the shadcn CLI

$ npx shadcn@latest add https://hairlineui.com/r/release-train.json

Registered the namespace? Then it’s shadcn add @hairline/release-train. Set it up

Templates

Need the whole page?

61 Next.js landing pages, each designed from scratch. Try any of them live; one is $39, all of them $159, and 6 are free.

All 61 templates

Where it’s used

  • Deploy and CI dashboards

    Preview, staging and production, what each runs, and promoting between them.

  • Release managers

    Moving a mobile or desktop build from beta to production channels.

  • Feature and model rollouts

    A model or config version moving from shadow to canary to everyone.

  • Internal admin tools

    Where each service’s version stands, with a rollback on the station that needs it.

What it handles for you

A deploy page of status badges shows a spinner and then a new number, so you can’t see what moved where, or what is still running while it deploys.

Instead of wiring upa deploy pipelineenvironment status badgesa promote buttona rollback menua deployment progress bara CI stepper
  1. What runs where

    Every environment shows the version it runs, in one column you can read down.

  2. Promote on the rail

    A switch between two stations appears only where their versions differ.

  3. The old one keeps running

    The new version waits on the line with its progress until it’s live.

  4. Failure in place

    The chip stops, turns red and the reason folds open under the station with Retry.

  5. Rollback you can see

    The version that was pushed out comes back in from the side.

  6. Your data, your calls

    Plain records in; promote, retry and rollback are async functions that can refuse.

Overview

Deploy pages usually list environments as rows of status badges, and a promotion is a spinner that turns into a new version number, so you can’t see what moved where or what is still running while it deploys. Release train lays your environments down a rail, each with the version it runs in a chip at the end of its row. Between two stations whose versions differ sits a small switch on the rail. Press it and a copy of the version peels off the chip above and rides down to the line between the two stations, where it waits with a ring that fills with your progress while the old version still runs below. When the deploy is live it docks: the new chip slides into the slot and pushes the old one out to the side. If it fails, the chip stops on the line, its ring turns red with a small shake and the reason folds open under the station with Retry. A rollback brings the version that was pushed out back in from the side. The stations are your records and every action is one async function.

States

stations
Each environment is a station on a hairline rail: a dot in its chart colour, its name and URL, and the version it runs in a grey chip at the end of the row.
promote
Where a station’s version differs from the next one’s, a 20px switch with a down arrow sits on the rail between them. Pressed, it spins until the next station starts deploying; if your function throws it shakes and stays.
deploying
A copy of the chip glides from the station above to the line between the two (620ms) and waits there with a ring that fills to your progress (600ms ease), or spins while progress is unknown. The station’s dot turns hollow.
live
The waiting chip slides down into the slot (460ms) and the old one slides out to the side through a blur (380ms).
failed
The ring turns red with a ×, the chip shakes (380ms), the dot turns red and the reason folds open under the station (420ms) with Retry.
rollback
“Roll back to v1.41.1” shows under a station with a previous version. Pressed it reads Rolling back; when the version changes the old chip comes back in from the side and the current one leaves.
reduced motion
Chips change in place; folds and rings change without easing.

Usage

usage.tsx
import { ReleaseTrain } from "@/components/release-train";<ReleaseTrain  stages={[    { key: "staging", label: "Staging", version: "v1.42.0" },    { key: "production", label: "Production", version: "v1.41.2" },  ]}/>

Works with

Promote through your deploy API

Keep the stations in state from your API; a promote starts a deploy and you poll it until it’s live or failed.

example.tsx
"use client";import * as React from "react";import { ReleaseTrain, type ReleaseStage } from "@/components/release-train";export function Deploys({ initial }: { initial: ReleaseStage[] }) {  const [stages, setStages] = React.useState(initial);  React.useEffect(() => {    // Your deploy API returns each environment's version, status, incoming, progress and error.    const id = setInterval(async () => setStages(await fetch("/api/environments").then((r) => r.json())), 2000);    return () => clearInterval(id);  }, []);  async function post(path: string, body: object) {    const res = await fetch(path, { method: "POST", body: JSON.stringify(body) });    if (!res.ok) throw new Error(await res.text());    setStages(await res.json());  }  return (    <ReleaseTrain      title="Releases"      caption="web · main"      stages={stages}      onPromote={(from, to) => post("/api/promote", { from, to })}      onRetry={(env) => post("/api/retry", { env })}      onRollback={(env) => post("/api/rollback", { env })}    />  );}

Props

stages
ReleaseStage[]
In order down the rail: { key, label, detail?, version?, previous?, status?: "live" | "deploying" | "failed", incoming?, progress? (0–1), error? }.
title / caption= "Releases"
string
The heading and a short line beside it, e.g. the repo and branch.
onPromote
(from, to) => Promise<unknown> | void
Shows the switch between two stations whose versions differ. Set the next station deploying when it starts; throw to refuse.
onRetry
(key) => Promise<unknown> | void
Shows Retry under a failed deploy.
onRollback
(key) => Promise<unknown> | void
Shows “Roll back to …” on a station with a previous version.

Accessibility and motion

  • The list is an ordered list; each station is named with what it runs or what is deploying to it (“Production: deploying v1.42.0”). The switch is a button named “Promote v1.43.0 to Staging”, shown only where it can act; Retry and Roll back are Status buttons.
  • Chips glide by transform from where their version was a moment before (measured from layout, then one Web Animation each); a chip that leaves is kept just long enough for its exit.
  • Every action is one async function; the switch and buttons show pending until your stations change, and shake if the function throws.
  • Station colours come from your chart colours in turn. Installs Status button.
  • With reduced motion chips change in place.

Requirements

React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

The CLI also installs Status button.

Source

components/release-train.tsx
"use client";import * as React from "react";import { StatusButton, type ActionStatus } from "./status-button";/* ───────────────────────────────────────────────────────── * RELEASE TRAIN: where each version is running, and where it's going * *   stations   your environments down a rail, each with the version *              it runs now in a chip at the end of its row *   promote    the switch on the rail between two stations: press it *              and a copy of the version peels off the chip above and *              rides down to the line between the two stations *   deploying  it waits there, its ring filling with your progress, *              while the old version still runs below *   live       it docks: the new chip slides into the slot and pushes *              the old one out to the side *   failed     the chip stops on the line, its ring turns red with a *              small shake, and the reason folds open with Retry *   rollback   the version that was pushed out comes back in from the *              side and the current one leaves * * The stations are yours (plain records); every action is one async * function. Chips glide by transform from measured positions; the * card never re-renders while they move. * ───────────────────────────────────────────────────────── */export interface ReleaseStage {  key: string;  label: string;  /** A second line, e.g. the URL or region. */  detail?: string;  /** The version running here now. */  version?: string;  /** The version a rollback goes back to. */  previous?: string;  status?: "live" | "deploying" | "failed";  /** The version on its way here, while deploying or failed. */  incoming?: string;  /** 0–1 while deploying; leave it out for an open-ended wait. */  progress?: number;  /** Why the deploy failed. */  error?: string;}export interface ReleaseTrainProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {  stages: ReleaseStage[];  title?: string;  caption?: string;  /** Shows the switch between two stations whose versions differ. Throw to refuse. */  onPromote?: (from: string, to: string) => Promise<unknown> | void;  /** Shows Retry on a failed deploy. */  onRetry?: (key: string) => Promise<unknown> | void;  /** Shows Roll back on a station that has a previous version. */  onRollback?: (key: string) => Promise<unknown> | void;}const EASE = "cubic-bezier(0.16,1,0.3,1)";const GLIDE = "cubic-bezier(0.77,0,0.175,1)";const FOCUS = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 focus-visible:ring-offset-2 focus-visible:ring-offset-background";const reducedQuery = "(prefers-reduced-motion: reduce)";const subscribeReduced = (onChange: () => void) => {  const query = window.matchMedia(reducedQuery);  query.addEventListener("change", onChange);  return () => query.removeEventListener("change", onChange);};const useReducedMotion = () =>  React.useSyncExternalStore(subscribeReduced, () => window.matchMedia(reducedQuery).matches, () => false);type Leaving = { id: number; stage: string; version: string; to: "side" | "up" };let leavingId = 0;const transitOf = (s: ReleaseStage) => (s.status === "deploying" || s.status === "failed") && s.incoming ? s.incoming : null;export function ReleaseTrain({ stages, title = "Releases", caption, onPromote, onRetry, onRollback, className = "", ...props }: ReleaseTrainProps) {  const reduced = useReducedMotion();  const listRef = React.useRef<HTMLOListElement>(null);  const rects = React.useRef(new Map<string, { x: number; y: number }>());  const [actions, setActions] = React.useState<Record<string, ActionStatus>>({});  const [shake, setShake] = React.useState<Record<string, number>>({});  // Chips that leave a slot: kept for one exit animation.  const [prev, setPrev] = React.useState(stages);  const [leaving, setLeaving] = React.useState<Leaving[]>([]);  if (prev !== stages) {    const out: Leaving[] = [];    stages.forEach((s) => {      const was = prev.find((p) => p.key === s.key);      if (!was) return;      if (was.version && was.version !== s.version) out.push({ id: ++leavingId, stage: s.key, version: was.version, to: "side" });      const wasTransit = transitOf(was);      // A deploy that stopped without docking goes back up the rail.      if (wasTransit && !transitOf(s) && s.version !== wasTransit) out.push({ id: ++leavingId, stage: s.key, version: wasTransit, to: "up" });    });    setPrev(stages);    if (out.length) setLeaving((l) => [...l, ...out]);    // A station that starts deploying settles its switch.    const settled = stages.filter((s, i) => i > 0 && transitOf(s) && !transitOf(prev.find((p) => p.key === s.key) ?? s)).map((s) => s.key);    if (settled.length || stages.some((s) => s.status === "failed" && prev.find((p) => p.key === s.key)?.status !== "failed")) {      setActions((a) => {        const next = { ...a };        stages.forEach((s, i) => {          if (i > 0 && settled.includes(s.key)) delete next[`promote:${stages[i - 1].key}`];          if (s.status === "failed") delete next[`retry:${s.key}`];        });        return next;      });    }    const failedNow = stages.filter((s) => s.status === "failed" && prev.find((p) => p.key === s.key)?.status !== "failed").map((s) => s.key);    if (failedNow.length) setShake((m) => ({ ...m, ...Object.fromEntries(failedNow.map((k) => [k, (m[k] ?? 0) + 1])) }));  }  // Glide every chip that's new in its place from where its version was a moment ago.  React.useLayoutEffect(() => {    const list = listRef.current;    if (!list) return;    const base = list.getBoundingClientRect();    const before = rects.current;    const now = new Map<string, { x: number; y: number }>();    const chips = Array.from(list.querySelectorAll<HTMLElement>("[data-chip]"));    chips.forEach((el) => {      const r = el.getBoundingClientRect();      now.set(el.dataset.chip!, { x: r.left - base.left, y: r.top - base.top });    });    chips.forEach((el) => {      const id = el.dataset.chip!;      if (before.has(id) || reduced || !before.size) return;      const [kind, stage, version] = id.split("|");      const i = stages.findIndex((s) => s.key === stage);      const above = i > 0 ? stages[i - 1] : null;      const here = now.get(id)!;      const from =        kind === "dock"          ? (before.get(`transit|${stage}|${version}`) ?? (above?.version === version ? before.get(`dock|${above.key}|${version}`) : undefined))          : above?.version === version            ? before.get(`dock|${above.key}|${version}`)            : undefined;      if (from) {        el.animate([{ transform: `translate(${from.x - here.x}px, ${from.y - here.y}px)` }, { transform: "none" }], { duration: kind === "dock" ? 460 : 620, easing: GLIDE });      } else {        el.animate([{ transform: "translateX(18px)", opacity: 0, filter: "blur(3px)" }, { transform: "none", opacity: 1, filter: "blur(0px)" }], { duration: 420, easing: EASE, delay: 80, fill: "backwards" });      }    });    rects.current = now;  });  const run = (key: string, fn: () => Promise<unknown> | void, stage: string) => {    setActions((a) => ({ ...a, [key]: "pending" }));    let result: Promise<unknown> | void;    try {      result = fn();    } catch {      setActions((a) => ({ ...a, [key]: "error" }));      setShake((m) => ({ ...m, [stage]: (m[stage] ?? 0) + 1 }));      return;    }    Promise.resolve(result).then(      () => setActions((a) => (a[key] === "pending" && key.startsWith("rollback") ? { ...a, [key]: "idle" } : a)),      () => {        setActions((a) => ({ ...a, [key]: "error" }));        setShake((m) => ({ ...m, [stage]: (m[stage] ?? 0) + 1 }));      },    );  };  return (    <div className={`w-full rounded-[20px] bg-background shadow-[0_0_0_1px_var(--border)] ${className}`} data-release-train="" {...props}>      <div aria-hidden="true" data-natural-width className="grid h-0" style={{ gridTemplateColumns: "minmax(0, 420px)" }} />      <div className="@container w-full p-4 @md:p-5">        <div className="flex items-baseline justify-between gap-3">          <p className="truncate text-[12.5px] text-muted-foreground">{title}</p>          {caption && <p className="shrink-0 font-mono text-[11.5px] text-muted-foreground/80">{caption}</p>}        </div>        <ol ref={listRef} className="relative mt-2">          {/* The rail. */}          <span aria-hidden="true" className="absolute bottom-[26px] left-[9.5px] top-[26px] w-px bg-[color-mix(in_oklab,var(--foreground)_16%,var(--border))]" />          {stages.map((s, i) => {            const next = stages[i + 1];            const canPromote = !!onPromote && !!next && !!s.version && s.version !== next.version && !transitOf(next) && s.status !== "deploying";            const promoteKey = `promote:${s.key}`;            return (              <Station                key={s.key}                stage={s}                index={i}                reduced={reduced}                shake={shake[s.key] ?? 0}                leaving={leaving.filter((l) => l.stage === s.key)}                onLeft={(id) => setLeaving((l) => l.filter((x) => x.id !== id))}                retry={onRetry ? { status: actions[`retry:${s.key}`] ?? "idle", run: () => run(`retry:${s.key}`, () => onRetry(s.key), s.key) } : null}                rollback={                  onRollback && s.previous && s.previous !== s.version && !transitOf(s)                    ? { status: actions[`rollback:${s.key}`] ?? "idle", run: () => run(`rollback:${s.key}`, () => onRollback(s.key), s.key) }                    : null                }                promote={                  next                    ? {                        shown: canPromote || actions[promoteKey] === "pending",                        status: actions[promoteKey] ?? "idle",                        label: `Promote ${s.version ?? ""} to ${next.label}`,                        run: () => run(promoteKey, () => onPromote?.(s.key, next.key), next.key),                      }                    : null                }              />            );          })}        </ol>      </div>    </div>  );}interface StationProps {  stage: ReleaseStage;  index: number;  reduced: boolean;  shake: number;  leaving: Leaving[];  onLeft: (id: number) => void;  retry: { status: ActionStatus; run: () => void } | null;  rollback: { status: ActionStatus; run: () => void } | null;  promote: { shown: boolean; status: ActionStatus; label: string; run: () => void } | null;}function Station({ stage: s, index, reduced, shake, leaving, onLeft, retry, rollback, promote }: StationProps) {  const color = `var(--chart-${(index % 5) + 1}, var(--primary))`;  const transit = transitOf(s);  const failed = s.status === "failed";  const transitRef = React.useRef<HTMLSpanElement>(null);  const [error, setError] = React.useState(s.error ?? "");  if (failed && s.error && s.error !== error) setError(s.error);  React.useEffect(() => {    if (!shake || reduced) return;    transitRef.current?.animate([{ translate: "0 0" }, { translate: "-4px 0" }, { translate: "4px 0" }, { translate: "-2px 0" }, { translate: "0 0" }], { duration: 380, easing: "ease-out" });  }, [shake, reduced]);  const status = transit ? (failed ? `deploy of ${transit} failed` : `deploying ${transit}`) : s.version ? `running ${s.version}` : "nothing deployed";  return (    <li className="relative grid grid-cols-[20px_minmax(0,1fr)_auto] items-start gap-x-3 py-3" aria-label={`${s.label}: ${status}`}>      {/* The station on the rail. */}      <span aria-hidden="true" className="relative mt-[5px] flex size-5 items-center justify-center">        <span          className="size-[11px] rounded-full transition-[background-color,box-shadow] duration-300"          style={{            background: failed ? "var(--color-red-500, #ef4444)" : transit ? "var(--background)" : s.version ? color : "var(--background)",            boxShadow: transit && !failed ? `inset 0 0 0 2px ${color}` : s.version ? "0 0 0 3px var(--background)" : "inset 0 0 0 1.5px var(--border), 0 0 0 3px var(--background)",          }}        />      </span>      <div className="min-w-0">        <p className="truncate text-[13.5px] font-medium leading-[30px] tracking-[-0.01em] text-foreground">{s.label}</p>        {s.detail && <p className="-mt-1 truncate font-mono text-[11.5px] text-muted-foreground">{s.detail}</p>}        {/* Why it failed, and Retry. */}        <div className="grid transition-[grid-template-rows,opacity] duration-[420ms]" style={{ gridTemplateRows: failed ? "1fr" : "0fr", opacity: failed ? 1 : 0, transitionTimingFunction: EASE }}>          <div className="min-h-0 min-w-0 overflow-clip" inert={!failed}>            <p className="pt-1.5 text-[12px] leading-snug text-red-600 dark:text-red-400">{error || "The deploy failed."}</p>            {retry && (              <div className="pt-2">                <StatusButton size="sm" variant="outline" status={retry.status === "error" ? "error" : retry.status} labels={{ idle: "Retry", pending: "Retrying", success: "Retrying", error: "Retry" }} onClick={retry.run} />              </div>            )}          </div>        </div>        {/* Roll back. */}        <div className="grid transition-[grid-template-rows,opacity] duration-[420ms]" style={{ gridTemplateRows: rollback ? "1fr" : "0fr", opacity: rollback ? 1 : 0, transitionTimingFunction: EASE }}>          <div className="min-h-0 min-w-0 overflow-clip" inert={!rollback}>            <div className="pt-1.5">              <StatusButton                size="sm"                variant="ghost"                className="-ml-2"                status={rollback?.status ?? "idle"}                icon={<RollbackIcon />}                labels={{ idle: `Roll back to ${s.previous ?? ""}`, pending: "Rolling back", success: "Rolled back", error: "Try again" }}                onClick={rollback?.run}              />            </div>          </div>        </div>      </div>      {/* The slot: the running version docked; the incoming one waiting on the line above it. */}      <div className="relative mt-[3px] flex h-6 min-w-[64px] justify-end">        {s.version && (          <span key={`dock|${s.version}`} data-chip={`dock|${s.key}|${s.version}`} className="inline-flex h-6 items-center rounded-full bg-muted px-2.5 font-mono text-[11.5px] text-foreground tabular-nums">            {s.version}          </span>        )}        {leaving.map((l) => (          <LeavingChip key={l.id} leave={l} reduced={reduced} onDone={() => onLeft(l.id)} />        ))}        {transit && (          <span            ref={transitRef}            key={`transit|${transit}`}            data-chip={`transit|${s.key}|${transit}`}            className="absolute right-0 top-[-29px] z-10 inline-flex h-6 items-center gap-1.5 rounded-full bg-background pl-1.5 pr-2.5 font-mono text-[11.5px] text-foreground tabular-nums shadow-[0_0_0_1px_var(--border)]"          >            <Ring progress={s.progress} failed={failed} color={color} />            {transit}          </span>        )}      </div>      {/* The switch to the next station. */}      {promote && (        <button          type="button"          aria-label={promote.label}          aria-hidden={!promote.shown}          tabIndex={promote.shown ? 0 : -1}          disabled={promote.status === "pending"}          onClick={promote.run}          className={`absolute bottom-0 left-0 z-10 flex size-5 translate-y-1/2 cursor-pointer items-center justify-center rounded-full bg-background text-muted-foreground shadow-[0_0_0_1px_color-mix(in_oklab,var(--foreground)_18%,var(--border))] transition-[opacity,scale,color] duration-300 hover:text-foreground disabled:cursor-default ${FOCUS}`}          style={{ opacity: promote.shown ? 1 : 0, scale: promote.shown ? "1" : "0.6", pointerEvents: promote.shown ? "auto" : "none", transitionTimingFunction: EASE }}        >          {promote.status === "pending" ? (            <svg viewBox="0 0 16 16" className="size-3 animate-spin" fill="none" aria-hidden="true">              <circle cx="8" cy="8" r="5.5" stroke="currentColor" strokeOpacity="0.25" strokeWidth="2" />              <path d="M13.5 8A5.5 5.5 0 0 0 8 2.5" stroke="currentColor" strokeWidth="2" strokeLinecap="round" />            </svg>          ) : (            <svg viewBox="0 0 16 16" className="size-3" fill="none" aria-hidden="true">              <path d="M8 3.5v8.5M4.5 8.5 8 12l3.5-3.5" stroke="currentColor" strokeWidth="1.7" strokeLinecap="round" strokeLinejoin="round" />            </svg>          )}        </button>      )}    </li>  );}function LeavingChip({ leave, reduced, onDone }: { leave: Leaving; reduced: boolean; onDone: () => void }) {  const ref = React.useRef<HTMLSpanElement>(null);  const done = React.useRef(onDone);  React.useLayoutEffect(() => {    done.current = onDone;  });  React.useEffect(() => {    const el = ref.current;    if (!el || reduced) return void done.current();    const to = leave.to === "side" ? "translateX(26px)" : "translateY(-34px)";    const a = el.animate([{ transform: leave.to === "up" ? "translateY(-29px)" : "none", opacity: 1, filter: "blur(0px)" }, { transform: to, opacity: 0, filter: "blur(3px)" }], {      duration: 380,      easing: EASE,      delay: leave.to === "side" ? 120 : 0,      fill: "both",    });    a.onfinish = () => done.current();    return () => a.cancel();  }, [leave.to, reduced]);  return (    <span ref={ref} aria-hidden="true" className="absolute right-0 top-0 inline-flex h-6 items-center rounded-full bg-muted px-2.5 font-mono text-[11.5px] text-muted-foreground tabular-nums">      {leave.version}    </span>  );}function Ring({ progress, failed, color }: { progress?: number; failed: boolean; color: string }) {  const open = progress === undefined && !failed;  const p = failed ? 1 : Math.max(0, Math.min(1, progress ?? 0.3));  return (    <svg viewBox="0 0 16 16" className={`size-3.5 shrink-0 ${open ? "animate-spin" : ""}`} fill="none" aria-hidden="true">      <circle cx="8" cy="8" r="6" stroke="currentColor" strokeOpacity="0.14" strokeWidth="2" />      <circle        cx="8"        cy="8"        r="6"        transform="rotate(-90 8 8)"        stroke={failed ? "var(--color-red-500, #ef4444)" : color}        strokeWidth="2"        strokeLinecap="round"        pathLength={1}        strokeDasharray="1 1"        style={{ strokeDashoffset: 1 - p, transition: `stroke-dashoffset 600ms ${EASE}, stroke 300ms` }}      />      {failed && <path d="M6 6l4 4M10 6l-4 4" stroke="var(--color-red-500, #ef4444)" strokeWidth="1.6" strokeLinecap="round" />}    </svg>  );}function RollbackIcon() {  return (    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true">      <path d="M4 6.5h6a3 3 0 0 1 0 6H7" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />      <path d="M6.5 4 4 6.5 6.5 9" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />    </svg>  );}

Registry item: /r/release-train.json