# Agent Grid

The fleet view — every agent, its current status and how long it has been there.

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

## Install

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

## Import

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

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { AgentGrid } from "@wunderui/react"

export function Fleet() {
  const [selected, setSelected] = useState("collections")
  return (
    <AgentGrid
      columns={2}
      selectedId={selected}
      onSelect={(agent) => setSelected(agent.id)}
      agents={[
        { id: "collections", name: "Collections", status: "waiting" },
        { id: "triage", name: "Inbox triage", status: "running" },
      ]}
    />
  )
}
```

Expected result: You should see two cards side by side, each with a bot icon, the name and a status pill. The first has an indigo border; press the second and the border moves to it.

## When to use

### Use Agent Grid for

- The overview of every agent you run, with a status and a live counter on each
- Choosing an agent to open in a detail pane, with the choice kept in your state
- A read-only wall of agents with a Run or Pause button on each card

### Use something else

- [Run Timeline](https://wunderui.com/components/run-timeline) for the steps of one run, in order
- [Agent Lane](https://wunderui.com/components/agent-lane) for parallel workers inside one run
- [Agent Status](https://wunderui.com/components/agent-status) for one status pill on its own, for example in a header
- [List Group](https://wunderui.com/components/list-group) for a long, dense list of rows instead of cards

## Keyboard

Only a selectable grid has keyboard behaviour: each card is a button in the tab order and arrow keys do nothing. A read-only grid has no tab stops.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus from one card to the next, in reading order. Focus shows as an indigo border with a 2 px ring. A control in `action` is a tab stop of its own. |
| `Enter` or `Space` | Selects the focused card: `onSelect` is called with its agent and `aria-pressed` follows `selectedId`. Space does not scroll the page. |

## Behavior

How the grid lays out its cards, how selection works and what the cards do on their own.

- **Columns:** The column count is the widest layout: one column below 640 px, two from 640 px, the full number from 1024 px. Breakpoints follow the window width, not the grid's box.
- **Selection:** You own the selection. The grid highlights the card whose id matches and calls your handler with the pressed agent; pressing the selected card does not clear it.
- **Read only:** Without a selection handler a card is a plain box: no role, no tab stop, no hover fill. A selected id still draws the selected look, so a read-only grid can mark an agent.
- **Status:** Running and waiting agents tick a counter from their start time once a second. A finished agent with a start time shows the time since then; without one there is no counter.
- **Content:** The name is cut after one line, the description after two. The meta line wraps below the status on a narrow card, and cards in a row are as tall as the tallest.
- **Action:** Clicks on the action area never reach the card. In a selectable grid that makes a button inside a button, so keep actions for read-only grids.
- **Empty and loading:** The grid has no empty, loading or error state. With no agents it draws an empty grid; show your own state instead.
- **Hover and press:** A selectable card fills with the page colour on hover and the subtle colour while pressed; the selected card keeps the subtle fill.
- **Motion:** Only the running agent's status icon turns, and colours fade on hover and press.
- **Reduced motion:** With reduced motion on, the running icon stands still; the status word and counter say the same.

## Anatomy

- `AgentGrid`: A grid with 12 px between cards: one column on a phone, two on small screens, up to four on wide ones.
- `Agent card`: One agent in a bordered card with 16 px radius and padding. When selectable it can be pressed; the selected card has an indigo border and a subtle fill.
- `Icon`: The icon in a 36 px tile with a 12 px radius. Without one the tile shows a bot.
- `Name`: The name in 14 px semibold, on one line, cut with an ellipsis when long.
- `Description`: The description in 13 px secondary text, clamped to two lines.
- `Action`: A button or menu at the top right. Pressing it never selects the card.
- `Status`: A small Agent Status pill. A running or waiting agent counts up from its start time.
- `Meta`: A short fact in 12 px tertiary text next to the status, like 14 runs today. It wraps below the status on a narrow card.

## Best practices

### When to use

- Use it for the fleet overview: every agent, what each is doing and for how long. For the steps of one run use Run Timeline; for parallel workers in one run use Agent Lane.

### Do

- Set the start time to the moment the agent entered its current status. The pill counts from it, so nobody has to ask how long an agent has been stuck.
- When the grid drives a detail pane, pass the selection handler together with the selected id. The selected card gets the indigo border and aria-pressed.
- Keep the description to one sentence and put short facts in the meta line, such as 14 runs today.
- Show a skeleton, an Empty State or an Alert instead of the grid while it loads, when there are no agents or when the request fails. An empty list draws nothing.

### Don't

- Don't combine selection and an action: a selectable card is a button, and a button inside a button is invalid. Use actions in a read-only grid, or put controls in the detail pane.
- Don't expect arrow-key navigation. Every card is its own Tab stop; with many agents add a filter or search above the grid.
- Don't expect a second press to clear the selection. Pressing the selected card calls the handler again with the same agent.

## API reference

### AgentGrid

| Prop | Type | Default | Description |
|---|---|---|---|
| agents* | AgentSummary[] |  | The agents to show, in order. Each one has an `id` and a `name`, a `status` (`idle`, `running`, `waiting`, `done`, `failed` or `cancelled`) and optionally `description`, `since` (a Date, a timestamp or a date string), `icon`, `meta` and `action`. An empty list draws nothing. |
| className | string |  | Extra classes for the grid, for example `w-full`. |
| columns | 1 \| 2 \| 3 \| 4 | 3 | The widest layout, 1 to 4. Default 3. The grid shows fewer columns on narrower windows. |
| onSelect | (agent: AgentSummary) => void |  | Called with the agent that was pressed or chosen with Enter or Space. Passing it turns the cards into buttons. |
| selectedId | string |  | The `id` of the agent to draw as selected. It does not need `onSelect`. |

## Examples

### Columns: one, two or three

### Content: full, name and status, long text

### Status: idle, running, waiting, done, failed, cancelled

### Tint: a coloured icon tile per agent

## In context

### Fleet and detail: select an agent

Press a card, or focus it with Tab and press Enter or Space, and the panel under the grid follows the selection. The selection is yours: the grid shows the selected id and reports a press.

### States: ready, loading, empty, error

The grid has no loading, empty or error state, and an empty list draws nothing. Show a skeleton, an Empty State or an Alert in its place.

### Filter: only the agents that need you

A Segment narrows the list before it reaches the grid, and a status line says how many agents are shown. Needs you keeps the agents that wait for an answer or have failed.

## For AI agents

`get_component("agent-grid")`

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