Quick Start

Build your first working AI chatbot with react-ai-chat.

This guide uses the ready-made <Chatbot /> component. You will install the package, create a server-side chat route, connect an AI model, and render the chatbot in your React application.

If you want the chatbot UI source inside your project, see Generated Chatbot.

1. Install the dependencies

Install react-ai-chat and the AI SDK provider for the model you want to use.

npm install react-ai-chat @ai-sdk/google

react-ai-chat includes the ai package, so you do not need to install it separately.

2. Add your API key

Create or update your environment file:

GOOGLE_GENERATIVE_AI_API_KEY=your_api_key_here

Keep your API key on the server. Do not expose it through client-side environment variables.

3. Create the chat API route

Create a route for your chatbot.

For a Next.js App Router application:

app/
└── api/
    └── chat/
        └── route.ts

Add:

import { google } from "@ai-sdk/google";
import { createChatRoute } from "react-ai-chat/server";

export const POST = createChatRoute({
  model: google("your-model"),
});

createChatRoute() handles incoming chat messages and streams the model response back to the chatbot.

Your route can use an AI SDK-compatible language model.

For more server configuration options, see API Route.

4. Add the chatbot

Import Chatbot and the package stylesheet into your application.

import { Chatbot } from "react-ai-chat";
import "react-ai-chat/style.css";

export default function Page() {
  return <Chatbot />;
}

The chatbot uses /api/chat as its default API endpoint.

That matches the route created in the previous step.

At this point, start your development server and open your application. You should see the chatbot and be able to send a message.

5. Customize the chatbot

You can configure the ready-made chatbot through its props.

<Chatbot
  title="My AI Assistant"
  subtitle="Ask me anything"
  placeholder="Type your question..."
  position="bottom-right"
  initialOpen={true}
/>

You can also configure:

• Starter prompts
• Theme mode
• Theme tokens
• Icons
• Custom CSS classes
• API endpoints
• Error handling
• Chatbot text

See Chatbot UI for the complete configuration reference.

How it works

The basic request flow looks like this:

User
  ↓
<Chatbot />
  ↓
POST /api/chat
  ↓
createChatRoute()
  ↓
AI SDK model
  ↓
Streaming response
  ↓
<Chatbot />

The browser communicates with your API route. Your model provider credentials stay on the server.

Add your own knowledge with RAG

A basic chatbot uses the model's existing knowledge.

You can add RAG when you want the chatbot to retrieve information from your own documents, files, or other content.

Generate an embedding index with:

npx react-ai-chat embed

The CLI can configure the embedding provider, model, dimensions, fallback model, source documents, and output path.

Then connect the generated index to createChatRoute().

See RAG for the complete setup.

Generate an editable chatbot

The ready-made <Chatbot /> component is the fastest way to get started.

When you need deeper control over the UI, generate the chatbot components directly into your project:

npx react-ai-chat init

This creates editable React components and CSS:

chatbot/
├── chatbot.tsx
├── chatbot-header.tsx
├── chatbot-messages.tsx
├── chatbot-input.tsx
└── chatbot.css

The generated components use ChatbotProvider and useChatbotContext from react-ai-chat.

You can then change the structure, styling, message rendering, input behavior, and interaction patterns.

See Generated Chatbot to learn how it works.

What's next?