# Agent Lane

One parallel worker: its status, queue, throughput and the tasks it holds.

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

## Install

Agent Lane ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { AgentLane, AgentLaneStatus, AgentLaneTask } from "@wunderui/react"
```

## Minimal usage

Then use it:

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

export function DocsAudit() {
  return (
    <AgentLane
      name="Docs audit"
      status="active"
      queue={3}
      throughput={42}
      tasks={[
        { title: "Checking page 38 of 122", state: "Running" },
        { title: "Screenshot dark mode", state: "Queued" },
      ]}
    />
  )
}
```

Expected result: You should see a card with an indigo dot, Docs audit and Active, the line 3 queued, 42/min, and two task chips with their states under it.

## When to use

### Use Agent Lane for

- One worker of a run that fans out, shown next to the others
- A snapshot of where work piles up: the queue, the rate and the tasks in hand
- A lane that says in words whether it is active, idle or saturated

### Use something else

- [Agent Grid](https://wunderui.com/components/agent-grid) for agents as cards in a grid, each with its own run
- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of one run over time, with duration and result
- [Agent Status](https://wunderui.com/components/agent-status) for one pill that says what a run is doing right now

## Behavior

What the lane draws, what it leaves to you, and how it behaves for assistive technology and motion.

- **Structure:** A section named by the lane's name, with tasks as a list and the more line as one more list item. The lane keeps no state or timers: every number and word comes from props.
- **Status:** Each status changes the dot and the colour of the status word, and the word is always written out. The lane applies no rule of its own: it is saturated when you say so.
- **Metrics:** The line shows the queue and the rate per minute, printed as given, so 1842 has no thousands separator. Without throughput the rate is a dash; 0 shows 0/min.
- **Tasks:** Each task is a chip with a one-line title and an optional state. Titles end in an ellipsis with no tooltip; the more line shows only next to tasks, otherwise the empty text.
- **Failure and abort:** There is no failed or cancelled status. A failed task is text in its state and a stopped lane is idle; after an abort give each lane an empty text like Stopped, 9 tasks were not started.
- **Time:** A lane is the present: it has no time axis and no history of earlier runs. For a run over time use Run Timeline.
- **Selection and keyboard:** The lane is not interactive: no focus, hover, press or selected style, and no key does anything on it. A button stretched over the lane adds selection, as in the Examples tab.
- **Motion:** The lane has no animation or transition. A queue that changes is redrawn at once.
- **Reduced motion:** Nothing moves, so there is nothing to reduce. Every state is written as text as well as colour.

## Anatomy

- `AgentLane`: A section named by the lane's name, with a 1 px border and 16 px radius. It is not interactive: no role, no tab stop, no hover.
- `Status dot`: An 8 px dot, hidden from assistive technology. Indigo for active, grey for idle, yellow for saturated.
- `Name`: The name in 14 px semibold, on one line with an ellipsis. It names the section.
- `Status word`: Active, Idle or Saturated as visible text in the status colour, so the status is never colour alone.
- `Metrics`: One line such as 18 queued and 96/min, in tabular numbers. The rate shows a dash when there is no throughput.
- `Task`: A list item on a subtle tint with an 8 px radius: the title on one line with an ellipsis, and the state under it if there is one.
- `More line`: A last list item such as +16 more waiting, shown when the more count is above zero and the lane has tasks.
- `Empty text`: Shown in place of the task list when there are no tasks. The default is Waiting for a free slot.

## Best practices

### When to use

- Use it for one worker of a run that fans out, shown next to its peers to see where work piles up. For cards use Agent Grid, for steps over time Run Timeline, for one pill Agent Status.

### Do

- Set the status from the real queue. The lane draws what it is told and applies no threshold, so decide yourself when a lane counts as saturated.
- Pass the running task first, then the queued ones, and use the more count for the rest. Keep queue and more consistent: the lane does not derive one from the other.
- Show a failure as text in the task's state, in the red tint, and leave the lane idle if it stopped. There is no failed status.
- Show an aborted run as idle with a queue of 0 and an empty text that says how many tasks were not started.
- Give every lane its own name. A lane is a named section, which is a landmark, and lanes with the same name cannot be told apart.
- Lay lanes out in an auto-fit grid with a minimum width, say 180 px. A lane fills the width its parent gives it.

### Don't

- Don't expect it to take focus or a click. For a lane people can choose, put a button over it, as the Examples tab does.
- Don't expect to read a long task title: it ends in an ellipsis after one line, with no tooltip. Show the full title elsewhere.
- Don't pass the more count without tasks. The lane shows the empty text instead and the number is not drawn.

## API reference

### AgentLane

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | React.ReactNode |  | The name of the lane, one line with an ellipsis. It also names the section for assistive technology. |
| queue* | number |  | How many tasks wait in this lane, a number printed as it is (`18 queued`). |
| status* | "active" \| "idle" \| "saturated" |  | `active` (indigo), `idle` (grey) or `saturated` (yellow). The lane draws it and decides nothing; the word is written next to the dot. |
| className | string |  | Extra classes for the card, for example a hover fill or `border-primary` for a selected lane. A width comes from the parent. |
| emptyLabel | React.ReactNode | "Waiting for a free slot" | Shown when `tasks` is empty. Default `Waiting for a free slot`. |
| more | number |  | How many tasks are not shown as chips, drawn as `+16 more waiting`. Only drawn when the lane has tasks and the number is above zero. |
| tasks | AgentLaneTask[] | [] | The tasks to show as chips, each with a `title`, an optional `state` (text or an element) and an optional `id` used as the key. Empty by default. |
| throughput | number |  | Tasks per minute, a number printed as `96/min`. Left out, the lane shows a dash; `0` shows `0/min`. |

## Examples

### Tasks: two, more waiting, none, none with your own text

### Metrics: a rate, zero, no rate

### Task: with a state, without, a long title, a failed task

## In context

### Board: lanes that work through their queues, fail or are stopped

Press Start run. Three lanes finish tasks tick by tick and their queues shrink, and you can choose A lane fails to see Figma sync stop on a failed task, or press Stop run to idle every lane.

### Picker: choose a lane to see its tasks

A lane isn't interactive, so the board adds a button over each lane. Tab moves between lanes and Enter or Space selects one, which shows its tasks below with full titles, and pressing again clears it.

## For AI agents

`get_component("agent-lane")`

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