@openuidev/react-headless

Use this package when you want headless chat state + streaming, with or without prebuilt UI.

Import

import {
  ChatProvider,
  useThread,
  useThreadList,
  openAIAdapter,
  openAIResponsesAdapter,
  openAIReadableStreamAdapter,
  agUIAdapter,
  openAIMessageFormat,
  openAIConversationMessageFormat,
  identityMessageFormat,
  processStreamedMessage,
  MessageProvider,
  useMessage,
  EventType,
} from "@openuidev/react-headless";

`ChatProvider`

Provides chat/thread state to UI components.

type ChatProviderProps = ThreadApiConfig &
  ChatApiConfig & {
    streamProtocol?: StreamProtocolAdapter;
    messageFormat?: MessageFormat;
    children: React.ReactNode;
  };

ThreadApiConfig:

Provide threadApiUrl, or
Provide custom handlers: fetchThreadList, createThread, deleteThread, updateThread, loadThread

ChatApiConfig:

Provide apiUrl, or
Provide processMessage({ threadId, messages, abortController })

`useThread()`

Thread-level state/actions used throughout chat docs.

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

Shape:

type ThreadState = {
  messages: Message[];
  isRunning: boolean;
  isLoadingMessages: boolean;
  threadError: Error | null;
};

type ThreadActions = {
  processMessage: (message: CreateMessage) => Promise<void>;
  appendMessages: (...messages: Message[]) => void;
  updateMessage: (message: Message) => void;
  setMessages: (messages: Message[]) => void;
  deleteMessage: (messageId: string) => void;
  cancelMessage: () => void;
};

`useThreadList()`

Thread list state/actions for sidebars and history.

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

`useMessage()`

Access the current message inside a message component.

function useMessage(): Message;

Provided via MessageProvider / MessageContext.

Stream adapters

Adapters referenced in integration guides:

function openAIAdapter(): StreamProtocolAdapter; // OpenAI Chat Completions stream
function openAIResponsesAdapter(): StreamProtocolAdapter; // OpenAI Responses stream
function openAIReadableStreamAdapter(): StreamProtocolAdapter; // OpenAI ReadableStream
function agUIAdapter(): StreamProtocolAdapter; // AG-UI protocol stream

Related type:

interface StreamProtocolAdapter {
  parse(response: Response): AsyncIterable<AGUIEvent>;
}

Message format adapters

Converters referenced in integration guides:

const openAIMessageFormat: MessageFormat; // Chat Completions format
const openAIConversationMessageFormat: MessageFormat; // Responses/Conversations item format
const identityMessageFormat: MessageFormat; // Pass-through (no conversion)

Base type:

interface MessageFormat {
  toApi(messages: Message[]): unknown;
  fromApi(data: unknown): Message[];
}

Message types

type Message =
  | UserMessage
  | AssistantMessage
  | SystemMessage
  | DeveloperMessage
  | ToolMessage
  | ActivityMessage
  | ReasoningMessage;

Key message shapes:

interface UserMessage {
  role: "user";
  id: string;
  content: InputContent[];
}

interface AssistantMessage {
  role: "assistant";
  id: string;
  content: string | null;
  toolCalls?: ToolCall[];
}

Streaming utilities

function processStreamedMessage(/* ... */): Promise<void>;

Low-level utility for processing a streamed response outside of ChatProvider.

On this page