Headless Introduction

This page introduces headless mode and the role of ChatProvider in a custom chat UI.

The trade-off is simple: you get full control over rendering, but you become responsible for composing the sidebar, message list, and composer yourself.

At the center is ChatProvider, which manages:

streaming state
thread list and selection
message sending/cancelation
thread-history hooks

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

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

ChatProvider accepts the same backend props as the built-in layouts:

apiUrl or processMessage
streamProtocol
messageFormat
threadApiUrl or custom thread functions

Thread history is not automatic. To load and save threads, you still need threadApiUrl or the custom thread handlers.

The usual build order is:

configure ChatProvider with your backend connection
read state with useThread() and useThreadList()
render your own sidebar, messages, and composer components

Related guides

On this page