# Activity Item

One line in a live activity stream: status, action, tool and elapsed time.

- Category: AI & Agents
- Page: https://wunderui.com/components/activity-item
- Tier: Core and Pro

## Install

Activity Item ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ActivityItem } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ActivityItem } from "@wunderui/react"

export function Action() {
  return (
    <ActivityItem
      status="done"
      label="Read 214 variables from Figma"
      tool="figma.read"
      elapsed="3.6s"
    />
  )
}
```

Expected result: You should see a green dot, the label, a light indigo pill reading figma.read and 3.6s at the right edge. Set the status to running and the dot turns indigo and pulses.

## When to use

### Use Activity Item for

- One line in the live stream of what an agent is doing, with the tool and the time
- A feed of short events, grouped by day, where one line per event is enough
- A row that counts up while an action runs and settles on its duration

### Use something else

- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of a run with their output, duration and detail behind a disclosure
- [Agent Plan](https://wunderui.com/components/agent-plan) for a plan shown as a checklist before and while it runs
- [Log Stream](https://wunderui.com/components/log-stream) for the raw timestamped lines a run writes, with a filter and auto-scroll

## Behavior

What the row does with its status, its time cell, assistive technology and motion.

- **Structure:** A plain div: no list item, no role, no focus. The list, headings and live region around it are yours, and a data attribute mirrors the status for styling.
- **Status:** Each status has its own dot and a hidden word, so a screen reader reads Failed: Push to docs-preview timed out. On screen only the dot differs, so write the failure into the label too.
- **Counter:** A running row with a start time counts up every 100 ms (6.3s, then 1m 04s) and starts after first paint. When the status changes it shows the elapsed time, or a dash.
- **Live region:** The row announces nothing itself. Keep it out of log regions because the counter changes ten times a second, and announce start, finish and failure in one status line beside the list.
- **Long content:** The label ends in an ellipsis unless it wraps, and has no tooltip. The tool chip is cut at 160 px, and the time cell never shrinks, so a long label gives way first.
- **Failure and stop:** Failed is the one error state. There is no cancelled status: show a stopped step as failed with a label that says so, and unstarted steps as waiting with not started in the label.
- **States:** The row is not interactive. It has no hover, focus or pressed style and no tab stop.
- **Motion:** Only the running dot moves: it pulses in opacity. The counter is text.
- **Reduced motion:** With reduced motion on, the dot stands still. The counter keeps counting because it is information.

## Anatomy

- `ActivityItem`: One row in a feed. It is not a list item, a live region or a tab stop, so put it in a list item of your own.
- `Status dot`: An 8 px dot, hidden from assistive technology. Indigo and pulsing while running, green when done, red when failed, grey when waiting.
- `Label`: The label, 14 px, in the free width. It ends in an ellipsis or wraps if you ask, and a waiting row has a tertiary label.
- `Tool chip`: A light indigo pill with the tool name, up to 160 px wide. It shows only when a tool is set.
- `Time`: 12 px tertiary text with tabular numbers: the running counter, else the elapsed time, else a dash. It never shrinks.
- `Hidden status`: The status word plus a colon, as hidden text before the label. It is the only place a screen reader gets the status.

## Best practices

### When to use

- Use it for one line in a stream of actions: what happened, with which tool, and when. For steps with output use Run Timeline, for a plan use Agent Plan, for raw lines use Log Stream.

### Do

- Put rows in a list, one list item each. A screen reader then counts them, and a feed grouped by day gets a heading and a list per group.
- Say the failure in the label, like Push to docs-preview timed out. On screen only the dot's colour tells Done from Failed, and colour alone is not enough.
- Give a running row a start time, and pass the measured duration when it ends. The counter stops with the status, and without a duration the cell shows a dash.
- Announce changes from one status line next to the list, not from the rows. Mount the line before it has text.
- Let the label wrap where the whole text matters. A cut-off label has no tooltip.

### Don't

- Don't use it as a button or link. The row has no hover, focus or press style and no tab stop; use Run Timeline for steps that open.
- Don't put a running row inside a log or other live region. The counter changes ten times a second.
- Don't expect a cancelled state. Show a stopped step as failed with a label that says so, and steps that never started as waiting with not started in the label.
- Don't pass HTML strings or untrusted markup as the label. Tool and file names come from outside, so render them as text.

## API reference

### ActivityItem

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | React.ReactNode |  | What the action is, as text or parts (an actor, a verb, a target). It ends in an ellipsis unless `wrap` is set. |
| status* | "running" \| "done" \| "queued" \| "failed" \| "waiting" |  | `running` pulses and counts up from `since`, `done` and `failed` end the action, `waiting` has not started and waits for something, `queued` is lined up behind others (hollow dot). There is no cancelled status. The status word is also written as hidden text before the label. |
| aria-label | string |  | The spoken name of the button, for example "Start Write the changelog". Only used together with `onClick`. |
| className | string |  | Extra classes for the row, for example `w-full` or a margin. |
| elapsed | React.ReactNode |  | The text of the time cell, already formatted (`3.6s`, `5 min ago`), or an element such as a `time`. Shown when no counter runs; a dash when empty. |
| onClick | () => void |  | Makes the row a button, with hover, pressed and focus states. Without it the row is a plain `div`. |
| since | Date \| string \| number |  | When the action began, as a `Date`, a timestamp or a date string. A `running` row counts up from it every 100 ms; for any other status it is ignored. |
| tool | React.ReactNode |  | The tool, file or kind of event, as a light indigo pill. At most 160 px wide with an ellipsis. Left out, there is no chip. |
| wrap | boolean | false | Lets a long label break onto more lines instead of ending in an ellipsis. Default `false`. |

## Examples

### Tool: no chip, a tool chip, a long tool name

### Time: elapsed text, a counter that runs, a finished action, no time

### Label: short, truncated, wrapped, built from parts

### Queued and clickable

## In context

### Run: steps that wait, run, finish, fail or are stopped

Press Run again. Each step waits, runs with a counter and ends with its measured time, and you can choose Fails at step 3 to see a failure or press Stop run to end a step as stopped.

### Feed: who did what, grouped by day, with relative times

The label carries actor, verb and target, the chip carries the kind, and the right-hand text is the relative time in English. Grouping is the list around the rows: a heading and a list per day.

## For AI agents

`get_component("activity-item")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
