Getting Started

This guide will help you set up @cognipeer/chat-ui in your React application.

Installation

npm

npm install @cognipeer/chat-ui

yarn

yarn add @cognipeer/chat-ui

pnpm

pnpm add @cognipeer/chat-ui

Prerequisites

• React 18 or later
• A running @cognipeer/agent-server backend (or compatible API)

Quick Start

1. Import styles

import "@cognipeer/chat-ui/styles.css";

2. Add the Chat component

import { Chat } from "@cognipeer/chat-ui";
import "@cognipeer/chat-ui/styles.css";

function App() {
  return (
    <div className="h-screen">
      <Chat
        baseUrl="http://localhost:3000/api/agents"
        agentId="my-agent"
        theme="dark"
      />
    </div>
  );
}

3. That's it!

The Chat component will:

• Connect to your agent server
• Show a chat interface with input
• Display streaming responses
• Handle file uploads (pick, drag and drop, paste)
• Show conversation history with status badges
• Show approval and question cards when the agent pauses, and pick a turn up again after a reload (agent-server 0.3.0+)

agentId is optional: without it Chat lists the server's agents (GET /agents) and lets the person pick one.

With Authentication

If your agent server requires authentication:

<Chat
  baseUrl="http://localhost:3000/api/agents"
  agentId="my-agent"
  authorization="Bearer your-token"
/>

Without History Sidebar

For a minimal chat without history:

import { ChatMinimal } from "@cognipeer/chat-ui";

<ChatMinimal
  baseUrl="http://localhost:3000/api/agents"
  agentId="my-agent"
/>

Full Example

import { Chat } from "@cognipeer/chat-ui";
import "@cognipeer/chat-ui/styles.css";

export default function ChatPage() {
  return (
    <div className="h-screen bg-gray-900">
      <Chat
        baseUrl="/api/agents"
        agentId="assistant"
        theme="dark"
        streaming={true}
        enableFileUpload={true}
        onMessageSent={(message) => {
          console.log("User sent:", message);
        }}
        onMessageReceived={(message) => {
          console.log("Agent replied:", message);
        }}
        onError={(error) => {
          console.error("Chat error:", error);
        }}
      />
    </div>
  );
}

Component Sizing

The Chat component fills its container. Make sure the parent has a defined height:

// Good - parent has height
<div className="h-screen">
  <Chat ... />
</div>

// Good - explicit height
<div style={{ height: '600px' }}>
  <Chat ... />
</div>

// Bad - no height defined
<div>
  <Chat ... />
</div>

What's next after the basics

I want to...	Read
See what changed in 0.4.0	What's new in 0.4.0 and Migrating to 0.4.0
Let people approve tool calls and answer questions	Approvals and Questions
Survive reloads and stop runs for real	Running Turns and Stop
Show a usage meter and limit	Usage Limits
Build a workplace assistant (copy, feedback, terms, export)	Portal Experience
Put the chat in another site's page	Embedding the Chat
Change language or wording	Internationalization
Use another backend	Transports

Next Steps

• Theming - Customize colors and appearance
• Streaming - Real-time response handling
• File Uploads - Enable file attachments
• State Management - API-first vs React-controlled mode
• Accessibility - Keyboard, screen readers and focus
• Components - Component reference