Message Queue

The user hits send while the reply is in flight. You need a rule for that message: wait, ignore, or cut in.

By default the message waits in queue. It sends after the current run succeeds.

1. Show the pending queue#

useChat exposes queue separately from messages. cancelQueued(id) drops an item before it sends:

import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

const { messages, queue, sendMessage, cancelQueued } = useChat({
  connection: fetchServerSentEvents("/api/chat"),
});

function PendingQueue() {
  return (
    <>
      {queue.map((item) => (
        <div key={item.id} className="pending">
          {typeof item.content === "string" ? item.content : "[attachment]"}
          <button onClick={() => cancelQueued(item.id)}>Cancel</button>
        </div>
      ))}
    </>
  );
}

Render queue with a different style from messages. Once the text appears in queue or messages, clear the composer.

2. Pick whenBusy#

Pass a queue option. A string is shorthand for { whenBusy }:

import { useChat, fetchServerSentEvents } from "@tanstack/ai-react";

const { sendMessage } = useChat({
  connection: fetchServerSentEvents("/api/chat"),
  queue: { whenBusy: "queue", drain: "fifo", maxSize: 5 },
});

whenBusy is what happens to a send that arrives while the client is busy. The client is busy when a stream is active, a send is in flight, or the queue is draining:

• "queue" (default): hold the message. It sends once the run settles successfully.

• "drop": ignore the send. The promise still resolves. The message never appears in queue or messages. Keep the composer text and show feedback if you want a retry.

• "interrupt": abort the current stream and send the new message now. Already-queued messages stay. They drain after the interrupting send succeeds.

  Override the policy for one send with the second argument to sendMessage:

sendMessage("Never mind, do this instead", {
  whenBusy: "interrupt",
  body: { source: "composer" },
});

body is extra JSON for that request only. It is merged into forwardedProps.

Later#

• drain: "fifo" (default) sends queued items one at a time in order. "batch" merges the queue into one send after a successful settle (strings join with \n, multimodal parts stay in order, last body wins).

• maxSize: caps how many messages can wait (0 means never queue).

• onOverflow: "reject" (default) ignores a send once maxSize is reached. "drop-oldest" evicts the oldest queued item to make room.

• Strategy function: pass a function as queue for per-send control. That form always drains FIFO. Per-call whenBusy still wins.

When the queue drains versus flushes#

• Drain (auto-send): only after a successful stream settle, including after tool continuations finish.

• Flush (discard without sending): on error or abort of the active generation (stop(), real stream errors), clear(), unsubscribe(), and reload().

• interrupt does not flush: existing queued items remain. They drain after the interrupting turn succeeds.

  The composer no longer fights the stream. A send while busy waits, drops, or cuts in, on purpose.