PrimitivesChatShell

Chat Shell

ChatShell is the shortest path to a working chat UI. Pass messages and handlers, and it composes MessageList, MessageBubble, TypingIndicator, StopButton, and Composer for you.

ChatShell ships with a full API table, a copyable example, and accessibility notes.

tsx

Installation

Install the package once, then import ChatShell from its direct entry point or from the root.

bash

pnpm add @agent-ui/react

tsx

import { ChatShell } from "@agent-ui/react/chat-shell";

Tailwind CSS v4 users: add @source "../node_modules/@agent-ui/react/src" to the global stylesheet so the library utilities are generated.

Usage

The example below is the same code that renders the preview. Copy it, swap in your own handlers, and ship.

tsx

1import { ChatShell, useChat } from "@agent-ui/react";
2 
3const chat = useChat({ onSend: async (text, reply) => reply("Hello!") });
4 
5<ChatShell
6  messages={chat.messages}
7  isStreaming={chat.isStreaming}
8  error={chat.error}
9  onSend={chat.send}
10  onStop={chat.stop}
11/>

API reference

Every prop ChatShell accepts, its type, default, and behaviour.

API reference for this component
Name	Type	Default	Description
messages	ChatMessage[]	—	Transcript; each message has id, role, content, timestamp, status, name.
isStreaming	boolean	false	Shows the typing indicator and stop button.
error	string \| null	—	Renders an inline error banner.
onSend	(text: string) => void	—	Composer send handler.
onStop	() => void	—	Abort handler for the stop button.
placeholder	string	"Send a message..."	Composer placeholder.
className	string	—	Inherits every native div attribute, including id, aria-, data-, onClick, and style.

Accessibility

Includes the MessageList live region, labelled controls, and an error alert with status semantics.

Use it with the rest of the library

ChatShell composes with MessageList, ChatShell, useChat, and the provider compose blocks. Browse the full reference or see all components in the gallery.

11 lines · copy-ready