import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
traceClass, traceLineClass, traceIconClass, traceTitleClass,
traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import { ChevronRightIcon, CircleCheckIcon } from '#lib/ui/lucide.ts';
const question = 'Add Open Graph metadata to the home page.';
const answer =
'Added Open Graph defaults to app/layout.tsx and a title, description and image for the home page in app/page.tsx.';
const tasks = [
{
title: 'Found the project files',
steps: ['Searched for generateMetadata', 'Read app/layout.tsx', 'Read app/page.tsx'],
},
{
title: 'Updated the page metadata',
steps: ['Edited app/layout.tsx', 'Edited app/page.tsx'],
},
];
// A finished task: past tense, closed, its steps a trace under the line.
function TaskRow(task: { title: string; steps: string[] }) {
return html`
<details data-slot="trace-collapsible" class=${traceCollapsibleClass()}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>${task.title}</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform [[open]>summary>&]:rotate-90')}>${ChevronRightIcon()}</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="trace" class=${traceClass()}>
${task.steps.map((step) => html`
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-title" class=${traceTitleClass()}>${step}</span>
</span>
`)}
</div>
</div>
</details>
`;
}
// The conversation once both tasks are done, so both are closed.
export default function TaskDemo() {
return html`
<div class="flex min-h-72 w-full max-w-sm flex-col gap-4 py-6 text-sm">
<div data-slot="message" data-align="end" class=${messageClass()}>
<div data-slot="message-content" class=${messageContentClass()}>
<div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
<div data-slot="bubble-content" class=${bubbleContentClass()}>${question}</div>
</div>
</div>
</div>
<div data-slot="message" data-align="start" class=${messageClass()}>
<div data-slot="message-content" class=${cn(messageContentClass(), 'gap-4')}>
<div data-slot="trace" class=${traceClass()}>
${tasks.map((task) => TaskRow(task))}
</div>
<p>${answer}</p>
</div>
</div>
<button type="button" data-slot="button" data-variant="outline" data-size="sm" class=${cn(buttonClass({ variant: 'outline', size: 'sm' }), 'mt-auto self-start')}>
Replay
</button>
</div>
`;
}
View Code
Task is a piece of work the agent is doing, such as finding the project files or updating a page. Each step, like a search, a read or an edit, appears under the task when the agent takes it.
Task is built with a trace, with a trace collapsible for each task.
Task or Plan
Both are a list of steps under a collapsible line. The difference is when the steps are known.
Use Plan when the agent decides the steps before it starts. Use Task when the steps come from the work itself, and the agent only knows the next one once it has taken the last.
Installation
Task is built with the Trace component.
Copy and paste the following code into your project.
/**
* Trace: a vertical timeline of steps (a tool call, a reasoning step, a
* deploy stage), each with an icon on a connecting line, a title and an
* optional collapsible detail. Tier-1 class helper; compose with plain
* elements and `<details>` for the collapsible part.
*
* shadcn parity:
* Trace → traceClass()
* TraceLine / TraceIcon → traceLineClass() / traceIconClass()
* TraceTitle / TraceDescription
* → traceTitleClass() / traceDescriptionClass()
* TraceCollapsible / TraceCollapsibleTrigger / TraceCollapsibleContent
* → <details> / <summary> / a div, with the
* trace collapsible helpers
*
* shadcn has no new-york version of this component, so its look in the
* default style is shadcn's vega style, the classic shadcn look.
*
* A11y (required for accessible output): a trace is an ordered list of steps,
* so render it as `<ol>` with each step an `<li>`. A step's status must be in
* text, not only in the icon colour ("Failed", "Done"), and a decorative icon
* takes `aria-hidden="true"`. A collapsible step is a native `<details>` with a
* `<summary>`, which carries the expanded state by itself.
*
* Design tokens used: --border, --muted-foreground, --foreground.
*
* @example
* ```html
* <ol class=${traceClass()} data-slot="trace">
* <li class=${traceLineClass()} data-slot="trace-line">
* <span class=${traceTitleClass()} data-slot="trace-title">Fetched the issue</span>
* </li>
* </ol>
* ```
*/
/** Set `data-slot="trace"` on the element. */
export function traceClass(): string {
return 'gap-2 *:has-[>[data-slot=trace-line]]:rounded-md *:has-[>[data-slot=trace-line]]:focus-visible:ring-3 *:has-[>[data-slot=trace-line]]:focus-visible:ring-ring/50 flex w-full min-w-0 flex-col *:has-[>[data-slot=trace-line]]:flex *:has-[>[data-slot=trace-line]]:w-fit *:has-[>[data-slot=trace-line]]:max-w-full *:has-[>[data-slot=trace-line]]:min-w-0 *:has-[>[data-slot=trace-line]]:text-start *:has-[>[data-slot=trace-line]]:outline-none';
}
/** Set `data-slot="trace-line"` on the element. */
export function traceLineClass(): string {
return 'gap-2 text-sm flex w-fit max-w-full min-w-0 items-center text-muted-foreground transition-colors in-[a,button]:cursor-pointer in-[a:hover,button:hover]:text-foreground data-[status=error]:text-destructive data-[status=error]:in-[a:hover,button:hover]:text-destructive data-[status=pending]:opacity-60 data-[status=running]:*:data-[slot=trace-title]:shimmer';
}
/** Set `data-slot="trace-icon"` on the element. */
export function traceIconClass(): string {
return "size-4 [&_svg:not([class*='size-'])]:size-4 [[data-slot=trace-title]~&]:-ms-1 flex shrink-0 items-center justify-center [&_svg]:pointer-events-none";
}
/** Set `data-slot="trace-title"` on the element. */
export function traceTitleClass(): string {
return 'min-w-0 truncate motion-reduce:shimmer-none';
}
/** Set `data-slot="trace-description"` on the element. */
export function traceDescriptionClass(): string {
return 'shrink-0 text-muted-foreground/70 tabular-nums';
}
/** Set `data-slot="trace-collapsible"` on the element. */
export function traceCollapsibleClass(): string {
return 'flex w-full min-w-0 flex-col';
}
/** Set `data-slot="trace-collapsible-trigger"` on the element. */
export function traceCollapsibleTriggerClass(): string {
return 'gap-1 rounded-md focus-visible:ring-3 focus-visible:ring-ring/50 group/trace-collapsible-trigger flex w-fit max-w-full min-w-0 cursor-pointer items-center text-start text-muted-foreground transition-colors outline-none hover:text-foreground has-[[data-status=error]]:text-destructive';
}
/** Set `data-slot="trace-collapsible-content"` on the element. */
export function traceCollapsibleContentClass(): string {
return 'mt-2 mb-1 ms-[calc(--spacing(2)-1px)] border-s pe-1 ps-4 leading-relaxed min-w-0 wrap-break-word text-muted-foreground';
}
Update the import paths to match your project setup.
Usage
import {
traceClass,
traceCollapsibleClass,
traceCollapsibleContentClass,
traceCollapsibleTriggerClass,
traceIconClass,
traceLineClass,
traceTitleClass,
} from '#components/ui/trace.ts';
<div data-slot="trace" class=${traceClass()}>
<details data-slot="trace-collapsible" open class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
<summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-title" class=${traceTitleClass()}>Found the project files</span>
</span>
<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>
${ChevronRightIcon()}
</span>
</summary>
<div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
<div data-slot="trace" class=${traceClass()}>
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${SearchIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Searched for app/page.tsx</span>
</span>
<a href="/files/app/page.tsx">
<span data-slot="trace-line" class=${traceLineClass()}>
<span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${FileTextIcon()}</span>
<span data-slot="trace-title" class=${traceTitleClass()}>Read app/page.tsx</span>
</span>
</a>
</div>
</div>
</details>
</div>
Status
Set the task's status from its steps. Write the title in the present tense while the task runs, and in the past tense once it is done.
Put several tasks in one trace. Keep the running task open with ?open=${running}, and it renders closed once it is done.
AI SDK
Stream each task as a data part with its own id, writing the task again with each new step. Where your component collects the parts, keep the latest part for each id, so a task updates in place instead of repeating. See AI SDK for streaming the parts from a 'use server' action.
yield { type: 'data-task', id: 'update', data: { title, steps } };
const tasks = message.parts.filter((part) => part.type === 'data-task');
Migrating from AI SDK Elements
If you used Task from AI SDK Elements, its wrapper lives in components/ai-elements/task.tsx. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:
API Reference
See Trace.