# Job queue

> A worker pool’s jobs grouped by what needs you: reviews first, each job’s status ring doubling as its clock, approvals and retries that call your server.

Queue dashboards are usually a table sorted by time, so the one job waiting for a human sits among a hundred that are fine. Job queue groups the jobs by what needs you: Needs review first, then Running, Failed, Queued and Completed, and when a job changes status its row glides into its new group. Each job’s status mark is also its clock: a running job’s ring fills with its progress, a review’s amber ring drains as its window runs out, and a failed job’s red ring fills until it retries by itself. The header shows the pool’s workers as hairline slots, each busy one filled to its job’s progress, beside the pace and a Pause that greys them all. Approve, Reject, Retry and Cancel call your async functions and show a pending state; the row then follows the jobs you pass, and rows you remove fold away. A payload or a stack opens in place under its row, with Copy. Laid out for the card’s own width: on a narrow card the buttons take a line of their own under the reason, on a wide one they sit at the end of the row.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/job-queue.json
```

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

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `number-roll`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/job-queue
- Registry item (source): https://hairlineui.com/r/job-queue.json

## Usage

```tsx
import { JobQueue } from "@/components/job-queue";

<JobQueue
  title="relay-workers"
  jobs={jobs}
  concurrency={8}
  throughput={24.6}
  onApprove={(id) => fetch(`/api/jobs/${id}/approve`, { method: "POST" })}
  onReject={(id) => fetch(`/api/jobs/${id}/reject`, { method: "POST" })}
  onRetry={(id) => fetch(`/api/jobs/${id}/retry`, { method: "POST" })}
/>
```

## With BullMQ

Poll the queue from a route handler and map BullMQ’s states onto the five statuses; jobs waiting for a person carry an approval.

```tsx
"use client";
import useSWR from "swr";
import { JobQueue, type JobItem } from "@/components/job-queue";

const post = (path: string) => fetch(path, { method: "POST" }).then((r) => { if (!r.ok) throw new Error(r.statusText); });

export function Workers() {
  // /api/jobs returns BullMQ jobs already mapped to JobItem: active → running (progress, processedOn → startedAt),
  // delayed with data.review → approval, failed → failed (failedReason, stacktrace[0], attemptsMade), waiting → queued.
  const { data, mutate } = useSWR<{ jobs: JobItem[]; throughput: number }>("/api/jobs", (u: string) => fetch(u).then((r) => r.json()), { refreshInterval: 1000 });
  const then = (p: Promise<void>) => p.then(() => mutate());
  return (
    <JobQueue
      title="relay-workers"
      jobs={data?.jobs ?? []}
      concurrency={8}
      throughput={data?.throughput}
      onApprove={(id) => then(post(`/api/jobs/${id}/approve`))}
      onReject={(id) => then(post(`/api/jobs/${id}/reject`))}
      onRetry={(id) => then(post(`/api/jobs/${id}/retry`))}
      onCancel={(id) => then(post(`/api/jobs/${id}/cancel`))}
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `jobs` | `JobItem[]` | – | The jobs, each with id, title, status ("approval" \| "running" \| "failed" \| "queued" \| "completed"), and optionally queue, progress (0–100), startedAt, durationMs, approval { reason, expiresAt, requestedAt }, error { message, stack, attempt, maxAttempts, retryAt, backoffMs } and payload. |
| `title` | `string` | `"dispatcher-pool"` | The pool or queue’s name. |
| `concurrency` | `number` | `8` | How many workers the pool has; one slot each in the header. |
| `throughput` | `number` | – | Jobs finished per second, shown in the header when given. |
| `isPaused / onTogglePause` | `boolean / (paused) => void` | – | Whether the pool is paused; controlled or not. |
| `onApprove / onReject` | `(id) => Promise<unknown> \| void` | – | For jobs waiting for review. Throw to keep the buttons and shake the row. |
| `onRetry` | `(id) => Promise<unknown> \| void` | – | Retry a failed job now. |
| `onCancel` | `(id) => Promise<unknown> \| void` | – | Remove a queued job. |

## States

- **groups**: Needs review, Running, Failed, Queued and Completed, each a quiet label with a rolling count. When a job’s status changes, its row glides to its new place (460ms) instead of jumping.
- **running**: The ring fills to the job’s progress (eased, 700ms); the percent, and from a wider card the running time, sit at the end of the row.
- **review**: An amber ring with “!” drains over the review window as one linear animation; the reason in amber, the time left, Approve and Reject.
- **failed**: A red ring with × fills until the retry is due; the error, the attempt, “retry in 0:08” and Retry now.
- **pending**: A pressed action shows a spinner and its label morphs (Approving, Rejecting, Retrying) until the jobs you pass change; if your function throws, the row gives a small shake and the buttons come back.
- **leave**: A job you remove folds away in place (380ms) rather than vanishing.
- **paused**: Pause morphs to Resume in amber; the worker slots and running rings turn grey.
- **reduced motion**: No glides, folds or draining rings: rows and rings change in place.

## What it handles

A queue table sorted by time hides the one job waiting for a person, shows progress in a column you have to read, and buries why a job failed in a log somewhere else.

- **What needs you comes first**: Jobs are grouped by status with reviews on top; a job that changes status glides to its new group.
- **The status mark is the clock**: A ring fills with progress, drains as a review window closes, and fills until a retry fires.
- **The pool at a glance**: Workers as hairline slots filled to their job’s progress, the pace, and how many reviews are waiting.
- **Your server stays the truth**: Actions call your async functions and show a pending state; the rows follow the jobs you pass.
- **Why it failed, in place**: The error, the attempt and the next retry on the row; the stack or payload opens under it with Copy.
- **Keyboard and screen readers**: Every action is a named button; each group is a labelled section; details are disclosures.

## Replaces

a background job table, an approval queue, a job progress bar, a retry countdown, a stack trace viewer, a worker pool status

## Where it fits

- **AI agent runs**: Tool calls and batches an agent queues, with the risky ones waiting for a person to approve.
- **Background job dashboards**: BullMQ, Celery, Temporal, Inngest or Trigger.dev jobs on one screen of your own app.
- **Payments and refunds**: Refunds or payouts over a limit, held for review with a clock on them.
- **Imports, exports and syncs**: Long syncs with their progress, and the failures with their stack and next retry.

## Notes

- The component never changes a job’s status itself: actions call your functions, and rows follow the jobs you pass.
- Each group is a labelled section; actions are named buttons (“Cancel search.reindex-catalog”); details are disclosures with aria-expanded.
- Status colours are only for status, and every status also has its own glyph and words.
- One clock ticks once a second for every time and countdown; the draining and filling rings are single linear animations, so nothing re-renders to move them. Folds clip with overflow: clip, so a focused button can never scroll a row’s title out of view.
- Installs Number roll and Text morph. With reduced motion rows and rings change in place.

License: MIT (https://hairlineui.com/license#components)
