# Queue (/docs/agent-ui/components/queue)

Use a queue to show the work an agent has lined up and what it has already finished, and to let people change the order or take items out before the agent gets to them. Each section shows how many items it holds.

<Example caption="Press Tab to reach the queued items. Press Space to pick one up, the arrow keys to move it, and Space to drop it. Press Delete to remove one, or drag an item with the pointer.">
<Basic />

```tsx
"use client";
import { useState } from "react";
import { Queue } from "@/components/ui/queue";

const todo = [
  { id: "limits", status: "pending" as const, title: "Add tests for the limits" },
  {
    id: "docs",
    status: "pending" as const,
    title: "Document the rate limit headers",
    description: "README and the API reference",
  },
  { id: "changelog", status: "pending" as const, title: "Write the changelog entry" },
  { id: "middleware", status: "complete" as const, title: "Write the rate limit middleware" },
  { id: "read", status: "complete" as const, title: "Read the request handlers" },
];

export default function QueueExample() {
  const [items, setItems] = useState(todo);

  return (
    <Queue
      label="Agent queue"
      items={items}
      onReorder={(id, { index }) =>
        setItems((current) => {
          const moved = current.find((item) => item.id === id);
          if (!moved) return current;
          const rest = current.filter((item) => item !== moved);
          return [...rest.slice(0, index), moved, ...rest.slice(index)];
        })
      }
      onRemove={(id) => setItems((current) => current.filter((item) => item.id !== id))}
    />
  );
}
```
</Example>

## Installation [#installation]

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

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

## Composition [#composition]

```text
Queue
├── QueueSection
│   ├── QueueSectionTrigger
│   └── QueueSectionContent
│       └── QueueList
│           └── QueueItem
│               ├── QueueItemIcon
│               ├── QueueItemTitle
│               ├── QueueItemDescription
│               └── QueueItemRemove
└── QueueInstructions
```

`Queue` renders a Queued section and a Completed section when you pass no children, then the instructions. Each `QueueSection` takes a `value` of `pending` or `complete`, and hides while it has no items. Its trigger is a native button that shows or hides the section, with the section's title and count. `QueueList` renders an item for each of the section's items when you pass it no children, and each item shows its status mark, title, description and remove button unless you give it children. `QueueInstructions` holds the keys that move and remove items: it's hidden from sight, and screen readers read it with each item.

## Usage [#usage]

### Items [#items]

Pass the items as `items`, each with an `id`, a `title`, an optional `description` and a `status` of `pending` or `complete`. Pending items show under **Queued**, which starts open, and complete ones under **Completed**, which starts closed. Pass `defaultOpenSections`, like `["pending", "complete"]`, to start with others open. When the agent finishes an item, set its `status` to `complete` and keep its `id`, and it moves to Completed.

### Reordering [#reordering]

Pass `onReorder` to let people move queued items. It gets the item's `id`, and `details.index`, where the item goes in `items`. Move it there: the queue shows the order you pass back, and keeps showing the move until your next `items` arrive. Completed items stay where they are.

People drag an item with the pointer, or focus it and press Space or Enter to pick it up, the arrow keys to move it, Home and End to send it to either end, and Space or Enter to drop it. Escape puts it back. Screen readers hear each step, like "Dropped Write the changelog entry at position 1 of 3."

If the item being moved leaves `items`, the move is cancelled, `onReorder` isn't called, and focus moves to its neighbor.

### Removing [#removing]

Pass `onRemove` to let people remove items. It gets the item's `id`, and you take the item out of `items`. Each item shows a remove button on hover, and Delete or Backspace removes the focused item. Focus then moves to the next item, or the previous one at the end.

### Keyboard [#keyboard]

The items are one Tab stop. The arrow keys move between them, across both sections while Completed is open, and Home and End go to the first and last. Items in a closed section can't take focus.

### Motion [#motion]

A new item fades in once as it arrives. A removed item stays in place and fades out, hidden from assistive technology and out of reach, then the items after it slide up into its place. While an item moves, the others slide aside. Under `prefers-reduced-motion`, or with `motion="reduced"`, a removed item fades over 120 ms and nothing slides, and with `motion="none"` it leaves at once.

## API Reference [#api-reference]

### QueueOptions

| Prop                   | Type                                                                                                   | Description                                                                                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `items?`               | `readonly QueueItem[] \| undefined`                                                                    | The items, in order, keyed by `id`. Pending items show under Queued and complete ones under Completed. Default: `[]`                                                                                                    |
| `label?`               | `string \| undefined`                                                                                  | Names the queue for assistive technology and agents. Default: `"Queue"`                                                                                                                                                 |
| `onReorder?`           | `((id: string, details: ChangeDetails<QueueReorderReason> & { index: number; }) => void) \| undefined` | Called when someone moves a pending item, with its `id` and, in `details.index`, the index it moves to in `items`. Move it there: the queue shows your next `items`. While it's set, pending items can be reordered.    |
| `defaultOpenSections?` | `("complete" \| "pending")[] \| undefined`                                                             | The sections open at first. Default: `["pending"]`                                                                                                                                                                      |
| `onRemove?`            | `((id: string, details: ChangeDetails<"remove-press" \| "imperative">) => void) \| undefined`          | Called with an item's `id` when someone removes it. While it's set, items can be removed. An item is asked for once: a host that keeps it, say after a failed removal, passes a new object for it to allow another try. |
| `motion?`              | `"auto" \| "none" \| "reduced"`                                                                        | `"auto"` follows `prefers-reduced-motion`. A removed item fades out before the items after it move up; under `"none"` it leaves at once. Default: `"auto"`                                                              |

### Agent [#agent]

An agent connected with `createAgent` finds the queue by its `label` and reads its `items`, and can name an item by its title. It can run `reorder` while `onReorder` is set and two or more items are queued, and `remove` while `onRemove` is set. Both go through your callbacks, with `details.source` set to `agent`.

### QueueAgentActions

| Prop      | Type                                                    | Description                                                                                                                                                                                                                                                                                                                                       |
| --------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reorder` | `((id: string, index: number) => boolean) \| undefined` | Moves a pending item among the pending ones, so that as many pending items come before it as come before `index` in `items`, through `onReorder`, whose `details.index` is where that puts it in `items`. Returns whether it moved; an index outside `items` is refused. Offered only while `onReorder` is set and two or more items are pending. |
| `remove`  | `((id: string, event?: Event) => boolean) \| undefined` | Removes an item by its `id`, through `onRemove`. Returns whether it was asked; an item already asked isn't asked again until the host passes a new object for it. Offered only while `onRemove` is set and there are items.                                                                                                                       |

Neither action waits for a person to confirm, since each only changes the list. To ask the person first, return their answer from your `allow`, which also answers every action that does need a person:

```ts
import { createAgent } from "@ui-sdk/react/agent";

const agent = createAgent({
  allow: ({ component, action, confirm }) => {
    if (confirm) return window.confirm(confirm);
    if (component === "kind-queue") return window.confirm(`Let the agent ${action} a queued item?`);
    return true;
  },
});
```

<Caption>
Runs in React and Web Components. On `<kind-queue>`, `items` and `openSections` are properties only, and `label` and `motion` are attributes. Reordering needs the `can-reorder` attribute and fires `reorder`, and removing needs `can-remove` and fires `remove`, each with the item's `id` in `event.detail.value`; `reorder` also has `event.detail.index`. The element fills in its sections and items itself.
</Caption>