Polpo UI

A component library for building AI agent interfaces with Polpo. Composable chat components, tool renderers, session management, and agent views — wired to the Polpo SDK out of the box.

Why Polpo UI?

Building a chat interface for AI agents requires streaming, tool call rendering, session persistence, file attachments, ask-user flows, and more. Polpo UI handles all of that so you can focus on your product.

• Three composition levels — zero-config <Chat />, composable children, or headless primitives
• Works with any Polpo agent — coder, support, orchestrator, custom
• Neutral styling — ships Tailwind utility classes, fully themeable
• Dark mode ready — map gray tokens to your palette, dark mode works automatically
• Framework agnostic — works with Next.js, Vite, Remix, React Router, Astro, TanStack

Getting Started

New project (recommended)

Create a complete app from a starter template:

# Interactive — prompts for name and template
npx create-polpo-app

# Non-interactive — for CI and AI agents
npx create-polpo-app my-chat -t chat -y

Available templates:

Add to existing project

Via CLI (shadcn-style, copies source)

Requires shadcn/ui initialized in your project. Works with Next.js, Vite, Remix, React Router, Astro, TanStack, Laravel.

# Interactive
npx @polpo-ai/ui add chat

# Non-interactive — for CI and AI agents
npx @polpo-ai/ui add chat --overwrite

Components are copied into your project at components/polpo-chat/. You own the code — modify anything.

Via npm (compiled package)

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

Add this to your CSS so Tailwind scans the package classes:

/* Tailwind v4 */
@source "../node_modules/@polpo-ai/chat/dist/**/*.js";

// Tailwind v3 — tailwind.config.js
module.exports = {
  content: [
    "./app/**/*.{ts,tsx}",
    "./node_modules/@polpo-ai/chat/dist/**/*.js",
  ],
}

Quick Start

Wrap your app with PolpoProvider, then drop in a <Chat />:

import { PolpoProvider } from "@polpo-ai/react";
import { Chat } from "@polpo-ai/chat";

function App() {
  return (
    <PolpoProvider baseUrl="https://api.polpo.sh" apiKey="sk_live_...">
      <Chat agent="coder" />
    </PolpoProvider>
  );
}

That's it. Streaming, markdown, tool calls, input with file attachments, scroll-to-bottom, skeleton loading — all included.

Three Levels

Level 1 — Zero Config

<Chat sessionId="session_abc" agent="coder" />

Level 2 — Compose

<Chat sessionId="session_abc" agent="coder" avatar={<MyAvatar />}>
  <MyCustomInput />
</Chat>

Children replace the default input. Use useChatContext() from any child to access chat state.

Level 3 — Primitives

import { ChatMessage, ChatSkeleton, ToolCallChip } from "@polpo-ai/chat";
import { useChat } from "@polpo-ai/react";

// Build completely custom layouts with individual components

What's Included

Frameworks

Polpo UI works with any React 18+ framework:

• Next.js (App Router recommended)
• Vite
• Remix
• React Router
• Astro
• TanStack Start / Router
• Laravel

The "use client" directives on components are used by Next.js and ignored by other frameworks.

Next Steps

• Setup — Provider configuration, API key, baseUrl
• Usage — Composition patterns, session navigation, ask-user-question
• Theming — Colors, fonts, dark mode, Tailwind token mapping
• Polpo Stack — How the packages fit together