# Plan

Displays the steps the agent plans to take, and how far it has got.

Source: https://webjs.dev/ui/docs/ai-elements/plan

```ts
import { html, nothing } 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, traceDescriptionClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
  ChevronRightIcon, CircleCheckIcon, CircleDotIcon, CircleIcon, RouteIcon,
} from '#lib/ui/lucide.ts';

type Step = { title: string; status: 'done' | 'running' | 'pending' };

const plan: { title: string; steps: Step[] } = {
  title: 'Plan: migrate to Base UI',
  steps: [
    { title: 'Install @base-ui/react', status: 'done' },
    { title: 'Replace the Radix imports', status: 'done' },
    { title: 'Rename asChild to render', status: 'done' },
    { title: 'Run the type checker', status: 'done' },
  ],
};

const done = plan.steps.filter((step) => step.status === 'done').length;

function stepIcon(status: Step['status']) {
  if (status === 'done') return CircleCheckIcon();
  return status === 'running' ? CircleDotIcon() : CircleIcon();
}

// The conversation once the plan has finished: every step is done and the
// reply has streamed after it.
export default function PlanDemo() {
  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()}>Migrate the dialog components to Base UI.</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()}>
            <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-icon" aria-hidden="true" class=${traceIconClass()}>${RouteIcon()}</span>
                  <span data-slot="trace-title" class=${traceTitleClass()}>${plan.title}</span>
                  <span data-slot="trace-description" class=${traceDescriptionClass()}>${done} of ${plan.steps.length} done</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()}>
                  ${plan.steps.map((step) => html`
                    <span data-slot="trace-line" data-status=${step.status === 'pending' ? 'pending' : nothing} class=${traceLineClass()}>
                      <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${stepIcon(step.status)}</span>
                      <span data-slot="trace-title" class=${traceTitleClass()}>${step.title}</span>
                    </span>
                  `)}
                </div>
              </div>
            </details>
          </div>
          <p>Migrated Dialog and AlertDialog. The type checker passes.</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>
  `;
}
```

Plan is the list of steps the agent decides on before it starts, such as the steps of a migration. Each step is done, running or pending, and the title counts how many are done.

Plan is built with a trace, with a trace collapsible for the plan.

When the steps are not known up front, use [Task](https://webjs.dev/ui/docs/ai-elements/task#task-or-plan) instead.

## Installation

Plan is built with the [Trace](https://webjs.dev/ui/docs/components/trace) component.

```bash
npx @webjsdev/ui add trace
```

### Copy and paste the following code into your project.

````ts title="components/ui/trace.ts"
/**
 * 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

```ts
import {
  traceClass,
  traceCollapsibleClass,
  traceCollapsibleContentClass,
  traceCollapsibleTriggerClass,
  traceDescriptionClass,
  traceIconClass,
  traceLineClass,
  traceTitleClass,
} from '#components/ui/trace.ts';
```

```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" data-status="running" class=${traceLineClass()}>
        <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
          ${RouteIcon()}
        </span>
        <span data-slot="trace-title" class=${traceTitleClass()}>Plan: migrate to Base UI</span>
        <span data-slot="trace-description" class=${traceDescriptionClass()}>2 of 5 done</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()}>
            ${CircleCheckIcon()}
          </span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Replace the Radix imports</span>
        </span>
        <span data-slot="trace-line" data-status="running" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
            ${CircleDotIcon()}
          </span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Rename asChild to render</span>
        </span>
        <span data-slot="trace-line" data-status="pending" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>
            ${CircleIcon()}
          </span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Run the type checker</span>
        </span>
      </div>
    </div>
  </details>
</div>
```

## Details

Put a description above the steps, inside the trace collapsible content.

```ts
import { html, nothing } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass, traceDescriptionClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
  ChevronRightIcon, CircleCheckIcon, CircleIcon, RouteIcon,
} from '#lib/ui/lucide.ts';

const steps = [
  'Add a dark variant to the theme tokens',
  'Read the theme from a cookie on the server',
  'Add a toggle to the settings page',
  'Check contrast on the charts',
];

export default function PlanDescription() {
  return html`
    <div data-slot="trace" class=${cn(traceClass(), 'max-w-sm')}>
      <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-icon" aria-hidden="true" class=${traceIconClass()}>${RouteIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Plan: add dark mode</span>
            <span data-slot="trace-description" class=${traceDescriptionClass()}>1 of ${steps.length} done</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=${cn(traceCollapsibleContentClass(), 'flex flex-col gap-3')}>
          <p>
            Store the theme in a cookie so the server renders the right one and
            the page does not flash on load.
          </p>
          <div data-slot="trace" class=${traceClass()}>
            ${steps.map((step, index) => html`
              <span data-slot="trace-line" data-status=${index > 0 ? 'pending' : nothing} class=${traceLineClass()}>
                <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${index === 0 ? CircleCheckIcon() : CircleIcon()}</span>
                <span data-slot="trace-title" class=${traceTitleClass()}>${step}</span>
              </span>
            `)}
          </div>
        </div>
      </details>
    </div>
  `;
}
```

## AI SDK

Stream the plan as a data part with a fixed `id`, from the `'use server'` action that streams the reply. Each time the plan changes, yield it again with the same `id`, and keep the latest part for each `id` where your component collects the parts, so it updates in place.

```ts title="modules/chat/actions/chat.server.ts"
yield { type: 'data-plan', id: 'plan', data: { title, steps } };
```

```ts
const plan = message.parts.find((part) => part.type === 'data-plan');
```

See [AI SDK](https://webjs.dev/ui/docs/helpers/ai-sdk) for streaming the parts to a component.

## Migrating from AI SDK Elements

If you used Plan from [AI SDK Elements](https://elements.ai-sdk.dev), its wrapper lives in `components/ai-elements/plan.tsx`. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:

| AI SDK Elements | WebJs UI |
| --- | --- |
| `Plan` | A trace with a trace collapsible, in place of a Card. Keep `isStreaming` in your component. |
| `PlanHeader` | The collapsible's `<summary>`, holding a trace line. Set `data-status="running"` on the line while it streams, in place of the Shimmer. |
| `PlanTitle, PlanDescription` | A trace title, and a trace description like "2 of 4 done". |
| `PlanContent` | The trace collapsible content, holding a trace for the steps. |
| `PlanTrigger` | Nothing of its own, since the whole summary opens the plan. |
| `PlanAction` | A button next to the trace collapsible, not inside its `<summary>`, since a button cannot sit inside the trigger. |
| `PlanFooter` | A plain container. |

## API Reference

See [Trace](https://webjs.dev/ui/docs/components/trace#api-reference).
