@openuidev/react-headless

Headless React primitives, streaming adapters, and state management for OpenUI.

<<<<<<< nit/react-headless

Table of Contents

• @openuidev/react-headless
  • Table of Contents
  • Architecture Overview
  • Installation
    • Peer dependencies
  • Quick Start
    • Minimal setup (URL-based)
    • Custom backend functions
  • Core Concepts
    • ChatProvider
    • Hooks
    • Streaming
    • Message Formats
    • Stream Protocol Adapters
  • Module Breakdown
    • v2/ — Zustand Store & Provider
      • Store Internals
    • stream/ — Streaming Engine
    • types/ — Type Definitions
    • hooks/ — Message Context
  • API Reference
    • ChatProviderProps
      • Thread API (choose one):
      • Chat API (choose one):
      • Optional:
    • useThread
    • useThreadList
    • useMessage
    • processStreamedMessage
    • Stream Adapters
    • Message Format Converters
  • Type Reference
    • Message Types (from @ag-ui/core)
    • Store Types
    • Adapter Types
  • How It All Fits Together

Architecture Overview

┌──────────────────────────────────────────────────────────────┐
│                      <ChatProvider>                           │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐  │
│  │              Zustand Store (ChatStore)                  │  │
│  │                                                        │  │
│  │  ┌─────────────────┐    ┌───────────────────────────┐  │  │
│  │  │ ThreadListSlice  │    │     ThreadSlice            │  │  │
│  │  │                 │    │                           │  │  │
│  │  │ • threads[]     │    │ • messages[]              │  │  │
│  │  │ • selectedId    │    │ • isRunning               │  │  │
│  │  │ • loadThreads() │    │ • processMessage()        │  │  │
│  │  │ • createThread()│    │ • cancelMessage()         │  │  │
│  │  │ • deleteThread()│    │ • appendMessages()        │  │  │
│  │  │ • selectThread()│    │ • updateMessage()         │  │  │
│  │  │ • ...           │    │ • ...                     │  │  │
│  │  └─────────────────┘    └───────────┬───────────────┘  │  │
│  │                                     │                  │  │
│  └─────────────────────────────────────┼──────────────────┘  │
│                                        │                     │
│                           processMessage() calls:            │
│                                        │                     │
│  ┌─────────────────────────────────────▼──────────────────┐  │
│  │            Streaming Pipeline                          │  │
│  │                                                        │  │
│  │  fetch(apiUrl)  ──►  StreamProtocolAdapter.parse()     │  │
│  │                           │                            │  │
│  │                   AG-UI Events (SSE)                   │  │
│  │                           │                            │  │
│  │                processStreamedMessage()                │  │
│  │                    │         │         │                │  │
│  │             createMsg  updateMsg  deleteMsg             │  │
│  │                    └─────────┴─────────┘                │  │
│  │                           │                            │  │
│  │                   Zustand set(messages)                 │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                              │
│  Hooks:  useThread()  ·  useThreadList()  ·  useMessage()    │
└──────────────────────────────────────────────────────────────┘

Installation

pnpm add @openuidev/react-headless

Peer dependencies

pnpm add react react-dom zustand eventsource-parser tiny-invariant

Quick Start

Minimal setup (URL-based)

import { ChatProvider, useThread, useThreadList } from "@openuidev/react-headless";

function App() {
  return (
    <ChatProvider apiUrl="/api/chat" threadApiUrl="/api/threads">
      <ChatUI />
    </ChatProvider>
  );
}

function ChatUI() {
  const { messages, processMessage, isRunning } = useThread();
  const { threads, selectThread, loadThreads } = useThreadList();

  // ... render your chat UI
}

Custom backend functions

<ChatProvider
  processMessage={async ({ threadId, messages, abortController }) => {
    return fetch("/my/custom/endpoint", {
      method: "POST",
      body: JSON.stringify({ threadId, messages }),
      signal: abortController.signal,
    });
  }}
  fetchThreadList={async () => {
    const res = await fetch("/my/threads");
    return res.json(); // { threads: Thread[], nextCursor?: any }
  }}
  createThread={async (firstMessage) => {
    const res = await fetch("/my/threads", {
      method: "POST",
      body: JSON.stringify({ message: firstMessage }),
    });
    return res.json(); // Thread
  }}
>
  <ChatUI />
</ChatProvider>

Core Concepts

ChatProvider

The <ChatProvider> is the top-level React component that creates and owns the Zustand store. It accepts configuration for how to communicate with your backend (either URL strings for convention-based REST endpoints, or custom async functions) and makes the store available to all descendant components via React context.

The store is created once on mount via useState(() => createChatStore(config)), so config changes after mount are not picked up.

Hooks

The package exposes two primary hooks that select specific slices from the unified store:

• useThread() — Returns the current thread's messages, loading/running state, and actions to send/edit/delete messages.
• useThreadList() — Returns the list of threads, selection state, and actions to create/select/delete/update threads.

Both hooks use Zustand's useShallow for automatic shallow-equality memoization, preventing unnecessary re-renders. They also support an optional selector function for fine-grained subscriptions:

// Only re-renders when messages change
const messages = useThread((s) => s.messages);

// Only re-renders when thread count changes
const count = useThreadList((s) => s.threads.length);

Streaming

When processMessage() is called, the following pipeline executes:

1. An optimistic user message is appended to the store immediately.
2. If no thread is selected, one is created automatically (via createThread or threadApiUrl), or an "ephemeral" ID is used.
3. The message is sent to the backend via fetch(apiUrl, ...) or the custom processMessage function.
4. The response is piped through a StreamProtocolAdapter (default: AG-UI SSE format) which yields AGUIEvent objects.
5. processStreamedMessage() consumes these events and translates them into createMessage, updateMessage, and deleteMessage calls that update the Zustand store in real-time.

Supported event types:

• TEXT_MESSAGE_START — New assistant message begins
• TEXT_MESSAGE_CONTENT — Text delta appended to the current message
• TEXT_MESSAGE_END — Message streaming complete
• TOOL_CALL_START — A tool/function call begins
• TOOL_CALL_ARGS — Argument delta for a tool call
• TOOL_CALL_END — Tool call streaming complete
• RUN_ERROR — Error during the stream

Message Formats

A MessageFormat is a bidirectional converter between the internal AG-UI message format and whatever format your backend expects. It has two methods:

• toApi(messages) — Converts outgoing messages (sent to your backend)
• fromApi(data) — Converts incoming messages (loaded from your backend/storage)

Built-in formats:

Stream Protocol Adapters

A StreamProtocolAdapter parses a Response body into an AsyncIterable<AGUIEvent>. This decouples the streaming protocol from the business logic.

Built-in adapters:

Module Breakdown

v2/ — Zustand Store & Provider

This is the heart of the package. The "v2" designation indicates it's the current API, replacing an earlier hook-based approach.

Store Internals

The store is a single flat Zustand store combining two logical slices:

ThreadListSlice manages the sidebar/thread list:

• threads: Thread[] — sorted by createdAt descending
• isLoadingThreads / threadListError / hasMoreThreads — loading state
• selectedThreadId — the active thread
• _nextCursor — internal pagination cursor
• Actions: loadThreads, loadMoreThreads, switchToNewThread, createThread, selectThread, updateThread, deleteThread

ThreadSlice manages the active conversation:

• messages: Message[] — the current thread's messages
• isRunning — whether a stream is in progress
• isLoadingMessages / threadError — loading state
• _abortController — internal abort controller for cancellation
• Actions: processMessage, appendMessages, updateMessage, setMessages, deleteMessage, cancelMessage

Key behaviors:

• Optimistic updates: processMessage appends the user message instantly before the network call.
• Auto thread creation: If no thread is selected when sending a message, the store auto-creates one (or uses "ephemeral" if no create function is configured).
• Abort on switch: selectThread and switchToNewThread cancel any in-flight stream via AbortController.
• Deduplication: mergeThreadList uses a Map keyed by threadId to merge paginated results without duplicates.
• Pending state: deleteThread and updateThread set isPending: true on the thread while the operation is in flight.

stream/ — Streaming Engine

types/ — Type Definitions

hooks/ — Message Context

API Reference

ChatProviderProps

The provider accepts a discriminated union config — you provide either URL strings or custom functions, but not both:

Thread API (choose one):

Chat API (choose one):

Optional:

useThread

function useThread(): ThreadState & ThreadActions;
function useThread<T>(selector: (state: ThreadState & ThreadActions) => T): T;

State:

Actions:

useThreadList

function useThreadList(): ThreadListState & ThreadListActions;
function useThreadList<T>(selector: (state: ThreadListState & ThreadListActions) => T): T;

State:

Actions:

useMessage

function useMessage(): { message: Message };

Returns the current message from MessageContext. Must be used inside a <MessageProvider>. This is primarily used by @openuidev/react-ui when rendering individual message components.

processStreamedMessage

function processStreamedMessage(params: {
  response: Response;
  createMessage: (msg: AssistantMessage) => void;
  updateMessage: (msg: AssistantMessage) => void;
  deleteMessage: (id: string) => void;
  adapter?: StreamProtocolAdapter;
}): Promise<AssistantMessage | void>;

Low-level utility that consumes an SSE response via the given adapter and calls the provided callbacks as the message is built up incrementally. Used internally by the store's processMessage action, but exported for advanced use cases.

Stream Adapters

import {
  agUIAdapter,
  openAIAdapter,
  openAIReadableStreamAdapter,
  openAIResponsesAdapter,
} from "@openuidev/react-headless";

// Use with ChatProvider
<ChatProvider streamProtocol={openAIAdapter()} apiUrl="/api/chat">
  ...
</ChatProvider>;

Message Format Converters

import {
  openAIMessageFormat,
  openAIConversationMessageFormat,
  identityMessageFormat,
} from "@openuidev/react-headless";

// For OpenAI Chat Completions backends
<ChatProvider messageFormat={openAIMessageFormat} streamProtocol={openAIAdapter()} apiUrl="/api/chat">
  ...
</ChatProvider>

// For OpenAI Responses API backends
<ChatProvider
  messageFormat={openAIConversationMessageFormat}
  streamProtocol={openAIResponsesAdapter()}
  apiUrl="/api/chat"
>
  ...
</ChatProvider>

Type Reference

Message Types (from @ag-ui/core)

Store Types

Adapter Types

How It All Fits Together

1. You wrap your app in <ChatProvider> with your backend config.
2. The provider creates a Zustand store with all thread and message management baked in.
3. Your UI components call useThread() and useThreadList() to read state and dispatch actions.
4. When a user sends a message, processMessage():
   • Appends an optimistic user message
   • Auto-creates a thread if needed
   • Sends the request to your backend
   • Streams the response through the adapter pipeline
   • Updates the store in real-time as tokens arrive
5. The MessageFormat layer handles serialization differences between AG-UI's internal format and your backend (OpenAI Completions, Responses API, or custom).
6. The StreamProtocolAdapter layer handles parsing differences between SSE protocols.

7. Everything is cancellable via AbortController — switching threads or calling cancelMessage() cleanly aborts in-flight streams.

Install

pnpm add @openuidev/react-headless

Docs

main

Detailed documentation is available at openui.com.