Polpo UI
Composable React chat components for Polpo AI agents. Three composition levels, three installation methods.
Install
New project
# Interactive
npx create-polpo-app
# Non-interactive (CI / AI agents)
npx create-polpo-app my-app -t chat -y
npx create-polpo-app my-app -t chat-widget -y
npx create-polpo-app my-app -t multi-agent -yAdd to existing project (shadcn-style, copies source)
# Interactive multi-select
npx @polpo-ai/ui add
# Non-interactive
npx @polpo-ai/ui add --all
npx @polpo-ai/ui add tools hooks --overwritenpm package (compiled)
npm install @polpo-ai/chat @polpo-ai/sdk @polpo-ai/react react-virtuoso lucide-react streamdownConsumer adds Tailwind scanning:
/* Tailwind v4 */
@source "../node_modules/@polpo-ai/chat/dist/**/*.js";// Tailwind v3 — tailwind.config.js
content: ["./node_modules/@polpo-ai/chat/dist/**/*.js"]Provider Setup
import { PolpoProvider } from "@polpo-ai/react";
// baseUrl is root URL — SDK appends /v1/ internally. Do NOT add /v1/.
<PolpoProvider baseUrl="https://api.polpo.sh" apiKey={process.env.NEXT_PUBLIC_POLPO_API_KEY} autoConnect={false}>
{children}
</PolpoProvider>Composition Levels
Level 1 — Zero Config
<Chat agent="coder" sessionId="session_abc" />Level 2 — Compose (children replace default input)
<Chat agent="coder" avatar={<Avatar />}>
<MyCustomInput />
</Chat>Level 3 — Primitives
import { ChatMessage, ChatSkeleton } from "@polpo-ai/chat";
import { useChat } from "@polpo-ai/react";Render Function Pattern
<Chat agent="coder" onSessionCreated={(id) => router.replace(`/chat/${id}`)}>
{({ hasMessages }) => hasMessages ? <ChatInput /> : <LandingPage />}
</Chat>Session Navigation
Package does NOT handle routing. Use onSessionCreated callback:
<Chat onSessionCreated={(id) => router.push(`/chat/${id}`)} />Components
| Component | Purpose |
|---|---|
Chat | Root compound — Provider + Messages + Input |
ChatInput | Textarea + submit + file attach + drag & drop |
ChatMessage | Message dispatcher (user/assistant) |
ChatMessages | Virtuoso list with auto-scroll |
ChatProvider | Context wrapping useChat + useFiles |
ChatSessionList | Flat session list with select/delete |
ChatSessionsByAgent | Sessions grouped by agent |
ChatAgentSelector | Agent picker dropdown |
ChatSuggestions | Suggestion button grid |
ChatAskUser | Ask-user-question wizard |
ChatLanding | Landing + greeting + input + suggestions |
ChatScrollButton | Scroll-to-bottom indicator |
ChatSkeleton | Loading skeleton |
ChatTyping | Typing dots |
ToolCallChip | Auto-dispatching tool renderer |
ToolCallShell | Base tool renderer with expand/collapse |
Hooks
const { messages, sendMessage, isStreaming, abort, uploadFile, pendingToolCall } = useChatContext();
const handleSubmit = useSubmitHandler(sendMessage, uploadFile);
const dragging = useDocumentDrag();References
- Component props: references/components.md — full props for every component
- Composition patterns: references/patterns.md — app assembly, ask-user, sessions, custom tools
- CLI commands: references/cli.md — create-polpo-app, @polpo-ai/ui, flags
- Theming: references/theming.md — colors, dark mode, fonts, Tailwind config