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 -y

Add 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 --overwrite

npm package (compiled)

npm install @polpo-ai/chat @polpo-ai/sdk @polpo-ai/react react-virtuoso lucide-react streamdown

Consumer 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