Background tasks
A tray of background jobs that opens from a status-bar button, with progress, open and cancel for each.
Loading preview…
Install
- 1
Run this command in your Tailwind CSS project. It adds
components/ai/background-tasks-default.tsxand installs its dependencies.$ npx shadcn@latest add https://gradientdeck.com/ai-components/r/background-tasks-default.json
Usage & API
Example
import { BackgroundTasks } from "@/components/ai/background-tasks-default"
<BackgroundTasks
tasks={[]}
onOpen={() => {}}
onCancel={() => {}}
/>Props BackgroundTasks
| Prop | Type & description | Required |
|---|---|---|
tasks | BackgroundTask[] | Required |
onOpen | (id: string) => void | Required |
onCancel | (id: string) => void | Required |
Dependencies
- React
- Tailwind CSS
- motion
- lucide-react
Implementation notes
Each row shows a mark, the title, the status line, and the actions. running uses a spinner. done uses a check. failed uses a cross, and the status line picks up the error color. queued and cancelled use the icon you passed. A cancelled title is struck through. Open is shown for every state except cancelled, and it calls onOpen with the id. A cancel icon is shown for running and queued, with a label of Cancel plus the title, and it calls onCancel with the id. The bar is drawn only when the task is running or queued and progress is not omitted. A running bar is the active color. A queued bar is neutral. The width is progress times the full track. There is no indeterminate animation. Omit progress if you do not want a bar.
Example
import { TaskQueue } from "@/components/ai/background-tasks-queue"
<TaskQueue
tasks={[]}
onCancel={() => {}}
onOpen={() => {}}
/>Props TaskQueue
| Prop | Type & description | Required |
|---|---|---|
tasks | QueuedTask[] | Required |
onCancel | (id: string) => void | Required |
onOpen | (id: string) => void | Required |
Dependencies
- React
- Tailwind CSS
- lucide-react
Implementation notes
The header reads Background work and a running count that ignores queued, done, failed and cancelled. Each row's mark is a spinner, a check, a cross for both failed and cancelled, or an empty circle for queued. The title button always calls onOpen. detail sits under it and truncates. The bar is present only when status is running and progress is set. Its accessible maximum is 100, and the width treats progress as a percent, clamped between 0 and 100. A queued task does not show a bar even if progress is 0. Cancel is available for running and for queued, and it is labeled Cancel plus the title. There is no Open text button, no icon prop and no all-finished phrase.
Choosing a layout
Use the tray when the jobs are ambient: a test suite, a migration, a notes draft, running while the person edits. The panel can list a mix of running, queued, done and failed work, and it can be closed without stopping anything. Open is how the person jumps to that job, and it is hidden once state is cancelled. Cancel is only on running and queued rows. A finished row keeps its status line, so a passed suite can still say how many tests passed. Put the panel next to the control that opened it. Nothing in the file portals or positions itself.
Use the queue when the background work is part of the page the person is already looking at, rather than a popover. The bar appears only while status is running and progress is set, so a queued job stays a row with a circle and no bar. Research progress is the wrong tray for a single research job inside a reply. It has phases and a topic, and it is not a list of unrelated jobs. A todo list is also the wrong shape. Its items are steps of the agent's plan, not processes with cancel. If one background job needs the person's permission before it runs, that permission is tool approval, and the job can join this list after it is allowed.
Are the two progress numbers on the same scale?
They are not. The tray's progress runs from 0 to 1, and the bar width is that fraction. Omit it for a job you cannot measure. The queue's progress is a percent: the bar's maximum is 100 and the width uses the number directly. A value of 1 on the queue is about one percent, not full. A value of 1 on the tray is full.
What does the header count as still running?
The tray counts state running and state queued, and it says all finished when that count is zero. Done, failed and cancelled do not count. The queue counts status running only. A job that is queued still appears in the list, but it does not increase the number in the header. Cancel on either layout is offered for both running and queued work.