Customization

Introduction

The ready-made <Chatbot /> component gives you control over the chatbot's content, position, icons, styling, theme, API endpoint, and error handling.

You can keep the existing UI and configure it through props. When you need to change the component structure itself, use the Generated Chatbot.

Text

Customize the text displayed throughout the chatbot.

<Chatbot
  title="Support Assistant"
  subtitle="We're here to help"
  triggerText="Chat with support"
  emptyStateText="What can we help you with?"
  placeholder="Type your question..."
  starterPromptsLabel="Popular questions"
/>

Text props

Starter prompts

Add predefined questions that users can select when the conversation is empty.

<Chatbot
  starterPrompts={[
    "What can you help me with?",
    "How does this work?",
    "Tell me about your services",
  ]}
/>

You can customize the label shown above the prompts:

<Chatbot
  starterPrompts={["What can you help me with?", "How does this work?"]}
  starterPromptsLabel="Popular questions"
/>

Starter prompts disappear once the conversation contains messages.

Position

Choose where the chatbot appears on the page.

<Chatbot position="bottom-right" />

Supported values:

bottom-right
bottom-left
top-right
top-left

The default position is bottom-right.

Custom icons

The chatbot accepts React nodes for its main controls.

<Chatbot
  triggerIcon={<ChatIcon />}
  sendIcon={<SendIcon />}
  closeIcon={<CloseIcon />}
/>

You can use an icon library or your own React components.

Custom CSS classes

Use classNames when you want to add your own CSS classes to specific chatbot elements.

<Chatbot
  classNames={{
    wrapper: "my-chatbot",
    trigger: "my-trigger",
    window: "my-window",
    header: "my-header",
  }}
/>

The available keys are:

This keeps the existing component structure while allowing you to customize its styling.

For deeper UI changes, see Generated Chatbot.

Theme mode

Control the chatbot's color mode with themeMode.

<Chatbot themeMode="light" />

<Chatbot themeMode="dark" />

<Chatbot themeMode="auto" />

With auto, the chatbot follows the user's system color preference.

Theme tokens

Use the theme prop when you need more control over the chatbot's appearance.

<Chatbot
  theme={{
    primaryColor: "#2563eb",
    primaryForeground: "#ffffff",
    background: "#ffffff",
    foreground: "#111827",
    mutedBackground: "#f3f4f6",
    mutedForeground: "#6b7280",
    borderColor: "#e5e7eb",
  }}
/>

Available theme tokens

You can also provide separate light and dark overrides:

<Chatbot
  theme={{
    primaryColor: "#7c3aed",
    light: {
      background: "#ffffff",
      foreground: "#18181b",
    },
    dark: {
      background: "#18181b",
      foreground: "#fafafa",
    },
  }}
/>

See Theming for the complete theme configuration.

API endpoint

The chatbot uses /api/chat by default.

Set apiEndpoint when your server route uses a different path:

<Chatbot apiEndpoint="/api/assistant" />

Your server must expose a POST handler at the same endpoint.

See API Route for server-side setup.

Initial state

Use initialOpen to control whether the chatbot is open when it first renders.

<Chatbot initialOpen />

The default is false.

Error handling

Use onError to respond to errors from the chatbot.

<Chatbot
  onError={(error) => {
    console.error("Chatbot error:", error);
  }}
/>

You can use this callback to connect the chatbot to your application's error reporting or display custom error UI.

See Errors for the available error types and codes.

Customizing the generated UI

Props are useful when you want to configure the existing chatbot interface.

When you need to change the React structure, generate the chatbot source into your project:

npx react-ai-chat init

The CLI creates editable React components and CSS:

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

You can modify the generated source directly, including:

• Component structure
• Message rendering
• Input behavior
• Header layout
• Styling
• Interaction patterns

The generated UI uses:

import { ChatbotProvider, useChatbotContext } from "react-ai-chat";

This lets you own the UI source while continuing to use the package's chat state and request handling.

See Generated Chatbot.

Complete example

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

export default function App() {
  return (
    <Chatbot
      title="Ahmed's Assistant"
      subtitle="Ask me anything"
      triggerText="Chat"
      position="bottom-right"
      initialOpen={false}
      placeholder="Ask a question..."
      emptyStateText="How can I help?"
      starterPrompts={[
        "What can you help me with?",
        "Tell me about this project",
      ]}
      starterPromptsLabel="Try asking"
      themeMode="auto"
      apiEndpoint="/api/chat"
      onError={(error) => {
        console.error(error);
      }}
    />
  );
}

Choosing the right approach

Use the ready-made <Chatbot /> when you want to configure the existing interface through props.

Use the generated chatbot when you need to change the component structure, message rendering, input behavior, or CSS directly.

Next steps