React SDK Documentation

The Chatbotkit React SDK provides a suite of React components and hooks for building chat interfaces. It includes everything needed for creating responsive, interactive chat experiences with features like auto-scrolling, dynamic text areas, and conversation management.

Installation

npm install @chatbotkit/react

# or using yarn
yarn add @chatbotkit/react
shell

Components

AutoScroller

A component that automatically scrolls to the latest content.

import { AutoScroller } from '@chatbotkit/react'

interface AutoScrollerProps {
  children: React.ReactNode
  enabled?: boolean
  smooth?: boolean
  offset?: number
}

function ChatContainer() {
  return (
    <AutoScroller>
      {/* Chat messages */}
    </AutoScroller>
  )
}
typescript

AutoTextarea

An auto-expanding textarea component that grows with content.

import { AutoTextarea } from '@chatbotkit/react'

interface AutoTextareaProps {
  value: string
  onChange: (e: React.ChangeEvent<HTMLTextAreaElement>) => void
  minRows?: number
  maxRows?: number
  placeholder?: string
  className?: string
  style?: React.CSSProperties
}

function ChatInput() {
  return (
    <AutoTextarea
      value={text}
      onChange={handleChange}
      minRows={1}
      maxRows={5}
      placeholder="Type a message..."
    />
  )
}
typescript

ChatInput

A specialized input component for chat interfaces.

import { ChatInput } from '@chatbotkit/react'

interface ChatInputProps {
  value: string
  onChange: (value: string) => void
  onSubmit: () => void
  disabled?: boolean
  placeholder?: string
  className?: string
}

function Chat() {
  return (
    <ChatInput
      value={message}
      onChange={setMessage}
      onSubmit={handleSubmit}
      placeholder="Type your message..."
    />
  )
}
typescript

ChatMessage

A component for rendering individual chat messages.

import { ChatMessage } from '@chatbotkit/react'

interface ChatMessageProps {
  message: {
    id: string
    type: 'user' | 'bot'
    text: string
    metadata?: Record<string, any>
  }
  className?: string
  avatar?: React.ReactNode
}

function Message({ message }) {
  return (
    <ChatMessage
      message={message}
      avatar={<UserAvatar />}
    />
  )
}
typescript

ChatMessages

A container component for rendering a list of chat messages.

import { ChatMessages } from '@chatbotkit/react'

interface ChatMessagesProps {
  messages: Array<{
    id: string
    type: 'user' | 'bot'
    text: string
  }>
  loading?: boolean
  className?: string
}

function MessageList() {
  return (
    <ChatMessages
      messages={messages}
      loading={isLoading}
    />
  )
}
typescript

ConversationManager

A component that manages the chat conversation state.

import { ConversationManager } from '@chatbotkit/react'

interface ConversationManagerProps {
  children: React.ReactNode
  endpoint: string
  initialMessages?: Array<Message>
  onError?: (error: Error) => void
}

function Chat() {
  return (
    <ConversationManager
      endpoint="/api/chat"
      initialMessages={[]}
    >
      {/* Chat interface components */}
    </ConversationManager>
  )
}
typescript

Hooks

useConversationManager

A hook for managing chat conversation state and interactions.

import { useConversationManager } from '@chatbotkit/react'

interface UseConversationManagerOptions {
  endpoint: string
  initialMessages?: Array<Message>
  onError?: (error: Error) => void
  onStreamStart?: () => void
  onStreamToken?: (token: string) => void
  onStreamComplete?: () => void
}

interface UseConversationManagerResult {
  messages: Array<Message>
  thinking: boolean
  text: string
  setText: (text: string) => void
  submit: () => Promise<void>
  clear: () => void
  error: Error | null
}

function ChatInterface() {
  const {
    messages,
    thinking,
    text,
    setText,
    submit,
    clear,
    error
  } = useConversationManager({
    endpoint: '/api/chat',
    onStreamStart: () => console.log('Stream started'),
    onStreamComplete: () => console.log('Stream completed')
  })

  return (
    // Chat interface implementation
  )
}
typescript

Types

interface SimpleMessage {
  id: string
  type: 'user' | 'bot'
  text: string
}

interface ComplexMessage extends SimpleMessage {
  metadata?: Record<string, any>
  timestamp?: number
  status?: 'pending' | 'sent' | 'error'
}

interface UseConversationManagerOptions {
  endpoint: string
  initialMessages?: Array<SimpleMessage | ComplexMessage>
  onError?: (error: Error) => void
  onStreamStart?: () => void
  onStreamToken?: (token: string) => void
  onStreamComplete?: () => void
}

interface UseConversationManagerResult {
  messages: Array<SimpleMessage | ComplexMessage>
  thinking: boolean
  text: string
  setText: (text: string) => void
  submit: () => Promise<void>
  clear: () => void
  error: Error | null
}
typescript

Examples

Complete Chat Implementation

import {
  AutoScroller,
  ChatInput,
  ChatMessages,
  useConversationManager
} from '@chatbotkit/react'

function Chat() {
  const {
    messages,
    thinking,
    text,
    setText,
    submit
  } = useConversationManager({
    endpoint: '/api/chat'
  })

  return (
    <div className="chat-container">
      <AutoScroller>
        <ChatMessages
          messages={messages}
          loading={thinking}
        />
      </AutoScroller>

      <ChatInput
        value={text}
        onChange={setText}
        onSubmit={submit}
        disabled={thinking}
        placeholder="Type a message..."
      />
    </div>
  )
}
typescript

Custom Message Rendering

import { ChatMessage, ChatMessages } from '@chatbotkit/react'

function CustomChatMessages({ messages }) {
  return (
    <ChatMessages>
      {messages.map(message => (
        <ChatMessage
          key={message.id}
          message={message}
          avatar={
            message.type === 'user'
              ? <UserAvatar />
              : <BotAvatar />
          }
          className={`message-${message.type}`}
        />
      ))}
    </ChatMessages>
  )
}
typescript

This documentation covers all the components and hooks shown in the screenshot. Would you like me to expand on any particular component or add more specific examples?