langgraph-react-chatbot

一个面向 React 的 AI 聊天组件库，基于 @langchain/langgraph-sdk 实现与 LangGraph 后端的流式通信。从 langgraph-vue3-chatbot 重构而来。

当前提供两个核心组件：

• AskAiBot：悬浮按钮 + 展开聊天窗，适合挂在页面右下角快速唤起
• ChatBot：可直接嵌入页面的聊天面板，适合详情页、工作台、后台系统等场景

组件内部已集成：流式消息渲染、工具调用展示、附件能力、建议问题、模型选择、多主题切换等常见 AI 聊天能力。

特性

• 开箱即用的 React AI 聊天组件
• 基于 LangGraph 的流式消息通信
• 同时支持嵌入式面板和悬浮聊天窗
• 内置工具调用展示
• 支持附件上传入口自定义渲染
• 支持建议问题、空状态、自定义消息内容渲染
• 自动引入组件样式，接入成本低
• 使用 TypeScript 编写，提供类型声明

安装

宿主项目需自行提供 react 和 react-dom，其余运行时依赖会随 langgraph-react-chatbot 自动安装。

pnpm add langgraph-react-chatbot

快速开始

1. 准备 LangGraph 服务

组件默认通过以下参数连接 LangGraph 后端：

• apiUrl：LangGraph 服务地址
• apiKey：LangGraph 服务访问凭证（可选）
• assistantId：目标 assistant 标识

2. 使用 AskAiBot

适合在现有页面中增加一个可随时唤起的 AI 助手入口。

import { AskAiBot } from 'langgraph-react-chatbot'

function App() {
  return (
    <>
      {/* 页面其他内容 */}
      <AskAiBot
        assistantId="research"
        assistantName="AI 助手"
        apiUrl="http://localhost:2024"
        theme="light"
        width={400}
        height="calc(100vh - 120px)"
        allowModelSwitch={false}
      />
    </>
  )
}

3. 使用 ChatBot

适合直接嵌入业务页面，作为主要聊天区域。

import { ChatBot } from 'langgraph-react-chatbot'

function App() {
  return (
    <div style={{ height: '600px' }}>
      <ChatBot
        assistantId="research"
        assistantName="AI 助手"
        apiUrl="http://localhost:2024"
        theme="dark"
        showHeaderActions={false}
        allowModelSwitch={false}
      />
    </div>
  )
}

推荐接入方式

如果你希望接入方式更贴近本仓库 demo，可以结合环境变量来传入配置：

import { ChatBot, AskAiBot } from 'langgraph-react-chatbot'
import type { AiBotTheme } from 'langgraph-react-chatbot'

const apiUrl = import.meta.env.VITE_LANGGRAPH_API_URL || 'http://localhost:2024'
const assistantId = import.meta.env.VITE_LANGGRAPH_ASSISTANT_ID || 'demo-assistant'
const assistantName = import.meta.env.VITE_LANGGRAPH_ASSISTANT_NAME || 'AI 助手'
const chatbotTheme: AiBotTheme = 'light'
const askAiBotTheme: AiBotTheme = 'dark'

const suggestions = [
  '这个 demo 怎么接入真实服务？',
  'ChatBot 和 AskAiBot 分别适合什么场景？',
]

function App() {
  return (
    <>
      <ChatBot
        apiUrl={apiUrl}
        assistantId={assistantId}
        assistantName={assistantName}
        theme={chatbotTheme}
      />

      <AskAiBot
        apiUrl={apiUrl}
        assistantId={assistantId}
        assistantName={assistantName}
        suggestions={suggestions}
        theme={askAiBotTheme}
      />
    </>
  )
}

Props

AskAiBot

| Prop | 用途 | 默认值 | | --- | --- | --- | | assistantId | 指定 LangGraph 侧的 assistant 标识 | 'research' | | assistantName | 设置组件头部展示的助手名称 | 'Chat' | | defaultExpanded | 控制悬浮聊天窗首次渲染时是否默认展开 | false | | systemPrompt | 设置发送给模型的系统提示词 | '用中文回答' | | threadId | 指定已有会话线程 id；不传时由组件内部创建线程。传固定值时可复用历史，并在刷新后自动尝试加入该线程最近的活跃对话流 | undefined | | userId | 标识当前用户，用于请求上下文区分 | 'user001' | | suggestions | 配置输入区上方的建议问题列表 | [] | | apiUrl | 指定 LangGraph 服务地址 | 'http://localhost:2024' | | apiKey | 指定 LangGraph 服务访问凭证 | undefined | | theme | 设置组件主题，可选 light / dark / hailan / dianshanglv / gaojizi | 'light' | | width | 设置悬浮聊天窗打开后的宽度，支持 number 或 CSS 尺寸字符串 | 400 | | height | 设置悬浮聊天窗打开后的高度，支持 number 或 CSS 尺寸字符串 | 'calc(100vh - 90px)' | | allowModelSwitch | 控制是否显示输入区右下角的模型选择器 | true |

ChatBot

| Prop | 用途 | 默认值 | | --- | --- | --- | | assistantId | 指定 LangGraph 侧的 assistant 标识 | 'research' | | assistantName | 设置聊天面板头部展示的助手名称 | 'Chat' | | systemPrompt | 设置发送给模型的系统提示词 | '你是一个有用的助手，帮用户解决各种问题。' | | threadId | 指定已有会话线程 id；不传时由组件内部创建线程。传固定值时可复用历史，并在刷新后自动尝试加入该线程最近的活跃对话流 | undefined | | userId | 标识当前用户，用于请求上下文区分 | 'user001' | | showHeaderActions | 控制是否显示聊天面板头部右侧操作按钮，例如关闭、最大化等 | true | | suggestions | 配置输入区上方的建议问题列表 | [] | | apiUrl | 指定 LangGraph 服务地址 | 'http://localhost:2024' | | apiKey | 指定 LangGraph 服务访问凭证 | undefined | | theme | 设置组件主题，可选 light / dark / hailan / dianshanglv / gaojizi | 'light' | | allowModelSwitch | 控制是否显示输入区右下角的模型选择器 | true |

组件实例 API

ChatBot 和 AskAiBot 都支持通过 ref 调用少量公开实例方法。

公共能力：

• setTextInput(text: string)：设置输入框文本
• addAttachments(attachments: PromptInputAttachment[])：添加附件，支持 file、data + mediaType、file_url 三种模式
• sendMessage()：触发现有发送流程

其中：

• ChatBot 会直接调用内部输入区现有逻辑
• AskAiBot 在折叠状态下调用 sendMessage() 时，会先自动展开再发送

AskAiBot 额外支持：

• open()：打开悬浮聊天窗
• close()：关闭悬浮聊天窗；如果当前处于最大化状态，会一并退出最大化

ChatBot 示例

PromptInputAttachment 推荐按以下三种模式传入：

1. 本地文件

{ type: 'file' | 'image', file: File, filename?: string, mediaType?: string }

• file：浏览器原生 File 对象
• filename / mediaType：可选覆盖默认文件名和 MIME 类型

2. 内联内容

{ type: 'file' | 'image', filename: string, mediaType: string, data: string }

• data：纯 base64 内容
• data 不要带 data:image/png;base64, 这类前缀
• mediaType：文件 MIME 类型，例如 image/png、application/pdf

3. 远程地址

{ type: 'file_url', url: string, filename?: string, mediaType?: string }

• url：远程文件地址
• filename / mediaType：可选补充展示信息

import { useRef } from 'react'
import { ChatBot } from 'langgraph-react-chatbot'
import type { AiBotPublicApi, PromptInputAttachment } from 'langgraph-react-chatbot'

function App() {
  const chatBotRef = useRef<AiBotPublicApi>(null)

  function askWithAttachment() {
    chatBotRef.current?.setTextInput('请帮我分析这些附件')

    const attachments: PromptInputAttachment[] = [
      {
        type: 'file_url',
        url: 'https://example.com/report.pdf',
        filename: 'report.pdf',
        mediaType: 'application/pdf'
      },
      {
        type: 'image',
        filename: 'architecture.png',
        mediaType: 'image/png',
        data: 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQIHWP4////fwAJ+wP9KobjigAAAABJRU5ErkJggg=='
      }
    ]

    chatBotRef.current?.addAttachments(attachments)
    chatBotRef.current?.sendMessage()
  }

  return (
    <>
      <button onClick={askWithAttachment}>发送预设问题</button>
      <div style={{ height: '600px', marginTop: 12 }}>
        <ChatBot
          ref={chatBotRef}
          assistantId="research"
          assistantName="AI 助手"
          apiUrl="http://localhost:2024"
        />
      </div>
    </>
  )
}

AskAiBot 示例

import { useRef } from 'react'
import { AskAiBot } from 'langgraph-react-chatbot'
import type { AskAiBotPublicApi } from 'langgraph-react-chatbot'

function App() {
  const askAiBotRef = useRef<AskAiBotPublicApi>(null)

  return (
    <>
      <div style={{ display: 'flex', gap: 8 }}>
        <button onClick={() => askAiBotRef.current?.open()}>打开助手</button>
        <button onClick={() => askAiBotRef.current?.close()}>关闭助手</button>
        <button onClick={() => {
          askAiBotRef.current?.setTextInput('帮我总结今天的待办')
          askAiBotRef.current?.sendMessage()
        }}>唤起并发送</button>
      </div>

      <AskAiBot
        ref={askAiBotRef}
        assistantId="research"
        assistantName="AI 助手"
        apiUrl="http://localhost:2024"
      />
    </>
  )
}

Render Props

React 版本使用 render props 替代 Vue 的 slots：

AskAiBot / ChatBot 通用

| Render Prop | 用途 | 参数 | | --- | --- | --- | | renderEmpty | 自定义空状态内容 | { sendMessage } | | renderCustom | 自定义 custom 消息渲染 | { customContent, threadId } | | renderAttachmentTrigger | 自定义附件触发器 | { addAttachments } |

样式说明

• 组件通过主入口导出
• 主入口会自动带出组件样式
• 使用时无需额外单独引入样式文件
• 当前内置五套主题：light（浅色，默认）、dark（深色）、hailan（海蓝）、dianshanglv（电商绿）、gaojizi（高级紫）
• AskAiBot 的 theme 会同时作用于外层悬浮按钮、内部 ChatBot 与 portal 浮层
• 内部 markdown 渲染基于 streamdown，支持代码高亮和 Mermaid 图表

使用建议

• 页面内主聊天区域优先使用 ChatBot
• 作为全局 AI 助手入口优先使用 AskAiBot
• 如果你已经有 thread id，可通过 threadId 复用已有会话
• 当传入固定 threadId 时，组件会先恢复线程历史；如果该线程存在 pending / running 的最近 run，会在页面刷新后自动重新加入流式对话
• 如果需要区分用户上下文，可传入 userId

本地开发

pnpm install
pnpm dev

构建生产版本：

pnpm build

预览构建结果：

pnpm preview

本地编译与发布

如果你是在维护这个组件库本身，常用命令如下。

本地编译组件库

pnpm install
pnpm build:lib

pnpm build:lib 会输出 npm 发布所需的库产物和类型声明到 dist-lib 目录。

发布到 npm

首次发布前先登录 npm：

npm login

然后执行：

pnpm publish --access public

说明：

• 当前包名是 langgraph-react-chatbot，发布时使用根目录 package.json
• prepublishOnly 会在发布前自动执行 npm version patch --no-git-tag-version，并运行 pnpm check:lib
• 如果只是想先手动验证构建结果，可以先执行 pnpm build:lib

技术栈

| 依赖 | 说明 | |------|------| | React 19 | UI 框架 | | TypeScript 6 | 类型系统 | | Vite 8 | 构建工具 | | Tailwind CSS v4 | 样式 | | @langchain/langgraph-sdk | LangGraph 客户端 | | streamdown | 流式 Markdown 渲染 | | Radix UI | 无头 UI 组件 | | lucide-react | 图标 |

相关链接

• npm: https://www.npmjs.com/package/langgraph-react-chatbot
• Repository: https://github.com/izerui/langgraph-react-chatbot
• Vue 3 版本: https://github.com/izerui/langgraph-vue3-chatbot

License

MIT