# Task (/docs/agent-ui/components/task)

Use a task to follow one piece of work an agent carries out, like a change across a few files. Its header shows how many steps are done, and it opens into the steps, each with its status and the files it touched.

<Example caption="Press Tab to reach the steps, then use the arrow keys to move between them. Press the title to hide or show them.">
<g />

```tsx
import { Task } from "@/components/ui/task";

export default function TaskExample() {
  return (
    <Task
      label="Add rate limiting to the API"
      items={[
        { id: "read", status: "complete", title: "Read the request handlers", files: ["src/server.ts"] },
        {
          id: "middleware",
          status: "running",
          title: "Write the rate limit middleware",
          files: ["src/middleware/rate-limit.ts"],
        },
        { id: "tests", status: "pending", title: "Add tests for the limits" },
      ]}
    />
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/task
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/task-web
```

## Composition [#composition]

```text
Task
├── TaskTrigger
│   ├── TaskIcon
│   ├── TaskTitle
│   └── TaskMeta
└── TaskContent
    └── TaskList
        └── TaskItem
            ├── TaskItemIcon
            ├── TaskItemTitle
            └── TaskItemFiles
```

`Task` renders the trigger and content when you pass no children. Its trigger is a native button that shows or hides the list. `TaskTitle` shows the `label`, or "Task" without one, and `TaskMeta` how many steps are complete, like "1 of 3". `TaskList` renders an item for each of the `items` when you pass it no children, and each item shows its status mark, title and files unless you give it children. `TaskItemFiles` renders only while the item has files.

## Usage [#usage]

### Items [#items]

Pass the steps as `items`, each with an `id`, a `status` of `pending`, `running`, `complete` or `error`, a `title` and optional `files`. Update an item's `status` as it runs, and keep its `id`: focus follows the id.

Without a `status` of its own, the task's status is what the items add up to: `error` once one fails, `complete` once all are complete, `running` once one runs or is complete, and `pending` before that. Pass `status` to set it yourself, like `awaiting-input` while the agent waits for an answer.

### Opening and Closing [#opening-and-closing]

The task opens and closes like a [Step](./step.mdx): it opens while it runs or waits for input, closes when it completes, and stays open when it fails, until someone opens or closes it. Pass `open` with `onOpenChange` to control it, or `autoOpen="never"` to keep it closed until someone opens it.

### Keyboard [#keyboard]

The items are one Tab stop. The arrow keys move between them, and Home and End go to the first and last. When the focused item is removed, focus moves to its neighbor. Screen readers read each item's status, then its title, and the running one as the current step.

### Streaming [#streaming]

A new item fades in once as it arrives, at the end of the list, so nothing above it moves. A status change morphs only the item's mark, so the rows never shift. A removed item leaves at once.

Screen readers hear an item's title and its outcome, like "Add tests for the limits complete", when it completes or fails, and nothing while it runs. Items that end in the same update, and the task itself, are read in one message.

### Motion [#motion]

Marks morph between statuses, and the list grows open and shut. Under `prefers-reduced-motion`, or with `motion="reduced"`, they fade over 120 ms instead and nothing moves or spins, and with `motion="none"` they change at once.

## API Reference [#api-reference]

### TaskOptions

| Prop               | Type                                                                                   | Description                                                                                                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kind?`            | `string \| undefined`                                                                  | Written as `data-kind`, for styling by step type.                                                                                                                                              |
| `open?`            | `boolean \| undefined`                                                                 | Whether the content shows. Passing it controls it: change it in `onOpenChange`.                                                                                                                |
| `defaultOpen?`     | `boolean \| undefined`                                                                 | Whether the content shows at first, when `open` isn't passed. Defaults to open while `status` is `running` or `awaiting-input`, unless `autoOpen` is `"never"`.                                |
| `onOpenChange?`    | `((open: boolean, details: ChangeDetails<StepOpenChangeReason>) => void) \| undefined` | Called when the step opens or closes, with what caused it.                                                                                                                                     |
| `autoOpen?`        | `"never" \| "running"`                                                                 | With `"running"`, the step opens while running or awaiting input and closes on completion, until someone toggles it. With `"never"`, only a person or your code opens it. Default: `"running"` |
| `durationSeconds?` | `number \| undefined`                                                                  | Written as `--kind-step-duration`.                                                                                                                                                             |
| `motion?`          | `"auto" \| "none" \| "reduced"`                                                        | `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`                                                                                                                                   |
| `items?`           | `TaskItem[] \| undefined`                                                              | The items, in order. Update an item's `status` as it runs, keeping its `id`. Defaults to none.                                                                                                 |
| `status?`          | `"awaiting-input" \| "cancelled" \| "complete" \| "error" \| "pending" \| "running"`   | Defaults to what the items add up to: `error` once one fails, `complete` once all are done, else `running` or `pending`.                                                                       |
| `label?`           | `string \| undefined`                                                                  | The title, which also names it in announcements. Defaults to "Task" or "Plan".                                                                                                                 |

### Agent [#agent]

An agent connected with `createAgent` finds the task by its title and reads its `open` and `status`. It can run these actions, and press the trigger like a person would.

### TaskAgentActions

| Prop       | Type            | Description                                               |
| ---------- | --------------- | --------------------------------------------------------- |
| `expand`   | `() => boolean` | Opens the step. Returns whether the change was accepted.  |
| `collapse` | `() => boolean` | Closes the step. Returns whether the change was accepted. |

<Caption>
Runs in React and Web Components. On `<kind-task>`, `items` is a property only, other props are kebab-case attributes, so `autoOpen` is `auto-open`, and `onOpenChange` fires `openchange`. The element fills in its parts when it has no children, and keeps a `<kind-task-item>` in its list for each item.
</Caption>