ai-elements

AI Elements

AI Elements 是一个全面的 React 组件库，用于构建 AI 驱动的用户界面。该库提供了 30 多个专为聊天界面、工具执行可视化、推理展示和工作流管理设计的组件。

安装

通过 shadcn 注册表安装：

npx shadcn@latest add https://ai-elements.vercel.app/r/[component-name]

导入模式：组件从各自的文件导入，而非通过统一导出文件导入：

// Correct - import from specific files
import { Conversation } from "@/components/ai-elements/conversation";
import { Message } from "@/components/ai-elements/message";
import { PromptInput } from "@/components/ai-elements/prompt-input";

// Incorrect - no barrel export
import { Conversation, Message } from "@/components/ai-elements";

前置检查（依赖示例前）

添加或接入 AI Elements 时，请按以下顺序操作，确保设置经过核验，而非想当然。

1. 安装每个组件 — 对所需的每个组件运行 npx shadcn@latest add https://ai-elements.vercel.app/r/[component-name]。

   • **通过标准：**命令成功完成，并且该组件的文件存在于项目的 components/ai-elements/ 下（或 components.json 为这些新增组件指定的目录中）。

2. 校准导入路径 — 每个 import … from "@/components/ai-elements/..." 都必须与代码仓库实际使用的别名和目录结构相符。

   • **通过标准：**每个导入都能解析到磁盘上的文件（IDE 导航或构建／tsc 不会针对这些路径显示“找不到模块”）。

3. 使 Tool / Confirmation 状态与 AI SDK 匹配 — 状态字符串（包括与审批相关的状态）取决于已安装的 ai 包主版本／版本。

   • **通过标准：**传给 ToolHeader、Tool 或 Confirmation 的状态，都能在你已安装的 AI SDK 版本文档或导出类型中找到，而不只是凭记忆照搬。

组件类别

对话组件

用于展示聊天式界面的组件，支持消息、附件和自动滚动行为。

• Conversation：支持自动滚动的容器
• Message：根据角色样式显示单条消息
• MessageAttachment：文件和图片附件
• MessageBranch：切换不同的回复

详情请参阅 references/conversation.md。

提示词输入组件

高级文本输入功能，支持文件附件、拖放、语音输入和状态管理。

• PromptInput：支持文件处理的表单容器
• PromptInputTextarea：自动扩展的文本区域
• PromptInputSubmit：状态感知型提交按钮
• PromptInputAttachments：文件附件显示
• PromptInputProvider：全局状态管理

详情请参阅 references/prompt-input.md。

工作流组件

用于展示作业队列、工具执行和审批工作流的组件。

• Queue：作业队列容器
• QueueItem：显示状态的单个队列项
• Tool：以可折叠状态展示工具执行
• Confirmation：审批工作流组件
• Reasoning：可折叠的思考／推理展示

详情请参阅 references/workflow.md。

可视化组件

基于 ReactFlow 的工作流可视化组件和自定义节点类型。

• Canvas：带有航空领域专用默认设置的 ReactFlow 封装器
• Node：带有连接点的自定义节点组件
• Edge：临时和动画边类型
• Controls、Panel、Toolbar：导航和控制元素

详情请参阅 references/visualization.md。

与 shadcn/ui 集成

AI Elements 构建于 shadcn/ui 之上，可与其主题系统无缝集成：

• 使用 shadcn/ui 的设计令牌（颜色、间距、字体）
• 通过 CSS 变量支持浅色／深色模式
• 兼容 shadcn/ui 组件（Button、Card、Collapsible 等）
• 遵循 shadcn/ui 的组件组合模式

关键设计模式

组件组合

AI Elements 采用组合优先的方法，通过较小的基础组件构建较大的组件：

<Tool>
  <ToolHeader title="search" type="tool-call-search" state="output-available" />
  <ToolContent>
    <ToolInput input={{ query: "AI tools" }} />
    <ToolOutput output={results} errorText={undefined} />
  </ToolContent>
</Tool>

基于上下文的状态

许多组件使用 React Context 管理状态：

• PromptInputProvider 用于全局输入状态
• MessageBranch 用于切换不同的回复
• Confirmation 用于审批工作流状态
• Reasoning 用于可折叠的思考状态

受控与非受控

组件同时支持受控和非受控模式：

// Uncontrolled (self-managed state)
<PromptInput onSubmit={handleSubmit} />

// Controlled (external state)
<PromptInputProvider initialInput="">
  <PromptInput onSubmit={handleSubmit} />
</PromptInputProvider>

工具状态机

Tool 组件遵循 Vercel AI SDK 的状态机：

1. input-streaming：正在接收参数
2. input-available：可执行
3. approval-requested：等待用户审批（SDK v6）
4. approval-responded：用户已响应（SDK v6）
5. output-available：执行已完成
6. output-error：执行失败
7. output-denied：审批未通过

队列模式

队列组件支持分层组织：

<Queue>
  <QueueSection defaultOpen={true}>
    <QueueSectionTrigger>
      <QueueSectionLabel count={3} label="tasks" icon={<Icon />} />
    </QueueSectionTrigger>
    <QueueSectionContent>
      <QueueList>
        <QueueItem>
          <QueueItemIndicator completed={false} />
          <QueueItemContent>Task description</QueueItemContent>
        </QueueItem>
      </QueueList>
    </QueueSectionContent>
  </QueueSection>
</Queue>

自动滚动行为

Conversation 组件使用 use-stick-to-bottom Hook 实现智能自动滚动：

• 新消息到达时自动滚动到底部
• 用户向上滚动时暂停自动滚动
• 不在底部时显示滚动到底部按钮
• 支持平滑和即时滚动模式

文件附件处理

PromptInput 提供全面的文件处理功能：

• 支持拖放（本地或全局）
• 支持粘贴图像和文件
• 文件类型验证（accept 属性）
• 文件大小限制（maxFileSize 属性）
• 文件数量上限（maxFiles 属性）
• 图像预览和文件图标
• 提交时自动将 Blob URL 转换为 Data URL

语音输入

PromptInputSpeechButton 使用 Web Speech API 进行语音输入：

• 基于浏览器的语音识别
• 连续识别模式
• 支持临时结果
• 自动将文本插入文本区域
• 录音期间提供视觉反馈

推理自动折叠

Reasoning 组件提供自动折叠行为：

• 开始流式传输时自动展开
• 流式传输结束 1 秒后关闭
• 以秒为单位跟踪思考时长
• 流式传输期间显示带闪烁效果的“正在思考……”
• 完成后显示“思考了 N 秒”

TypeScript 类型

所有组件都使用 TypeScript 提供完整的类型定义：

import type { ToolUIPart, FileUIPart, UIMessage } from "ai";

type ToolProps = ComponentProps<typeof Collapsible>;
type QueueItemProps = ComponentProps<"li">;
type MessageAttachmentProps = HTMLAttributes<HTMLDivElement> & {
  data: FileUIPart;
  onRemove?: () => void;
};

常见用例

聊天界面

组合使用 Conversation、Message 和 PromptInput，构建完整的聊天 UI：

import { Conversation, ConversationContent, ConversationScrollButton } from "@/components/ai-elements/conversation";
import { Message, MessageContent, MessageResponse } from "@/components/ai-elements/message";
import {
  PromptInput,
  PromptInputTextarea,
  PromptInputFooter,
  PromptInputTools,
  PromptInputButton,
  PromptInputSubmit
} from "@/components/ai-elements/prompt-input";

<div className="flex flex-col h-screen">
  <Conversation>
    <ConversationContent>
      {messages.map(msg => (
        <Message key={msg.id} from={msg.role}>
          <MessageContent>
            <MessageResponse>{msg.content}</MessageResponse>
          </MessageContent>
        </Message>
      ))}
    </ConversationContent>
    <ConversationScrollButton />
  </Conversation>

  <PromptInput onSubmit={handleSubmit}>
    <PromptInputTextarea />
    <PromptInputFooter>
      <PromptInputTools>
        <PromptInputButton onClick={() => attachments.openFileDialog()}>
          <PaperclipIcon />
        </PromptInputButton>
      </PromptInputTools>
      <PromptInputSubmit status={chatStatus} />
    </PromptInputFooter>
  </PromptInput>
</div>

工具执行显示

显示工具执行情况，并提供可展开的详细信息：

import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from "@/components/ai-elements/tool";

{toolInvocations.map(tool => (
  <Tool key={tool.id}>
    <ToolHeader
      title={tool.toolName}
      type={`tool-call-${tool.toolName}`}
      state={tool.state}
    />
    <ToolContent>
      <ToolInput input={tool.args} />
      {tool.result && (
        <ToolOutput output={tool.result} errorText={tool.error} />
      )}
    </ToolContent>
  </Tool>
))}

审批工作流

在执行操作前请求用户确认：

import {
  Confirmation,
  ConfirmationTitle,
  ConfirmationRequest,
  ConfirmationActions,
  ConfirmationAction,
  ConfirmationAccepted,
  ConfirmationRejected
} from "@/components/ai-elements/confirmation";

<Confirmation approval={tool.approval} state={tool.state}>
  <ConfirmationTitle>
    Approve deletion of {resource}?
  </ConfirmationTitle>

  <ConfirmationRequest>
    <ConfirmationActions>
      <ConfirmationAction onClick={approve} variant="default">
        Approve
      </ConfirmationAction>
      <ConfirmationAction onClick={reject} variant="outline">
        Reject
      </ConfirmationAction>
    </ConfirmationActions>
  </ConfirmationRequest>

  <ConfirmationAccepted>
    Action approved and executed.
  </ConfirmationAccepted>

  <ConfirmationRejected>
    Action rejected.
  </ConfirmationRejected>
</Confirmation>

作业队列管理

显示带完成状态的任务列表：

import {
  Queue,
  QueueSection,
  QueueSectionTrigger,
  QueueSectionLabel,
  QueueSectionContent,
  QueueList,
  QueueItem,
  QueueItemIndicator,
  QueueItemContent,
  QueueItemDescription
} from "@/components/ai-elements/queue";

<Queue>
  <QueueSection>
    <QueueSectionTrigger>
      <QueueSectionLabel count={todos.length} label="todos" />
    </QueueSectionTrigger>
    <QueueSectionContent>
      <QueueList>
        {todos.map(todo => (
          <QueueItem key={todo.id}>
            <QueueItemIndicator completed={todo.status === 'completed'} />
            <QueueItemContent completed={todo.status === 'completed'}>
              {todo.title}
            </QueueItemContent>
            {todo.description && (
              <QueueItemDescription completed={todo.status === 'completed'}>
                {todo.description}
              </QueueItemDescription>
            )}
          </QueueItem>
        ))}
      </QueueList>
    </QueueSectionContent>
  </QueueSection>
</Queue>

无障碍性

组件包含无障碍功能：

• ARIA 标签和角色
• 支持键盘导航
• 屏幕阅读器播报
• 焦点管理
• 语义化 HTML 元素

动画

许多组件使用 Framer Motion 实现流畅动画：

• 加载状态的闪烁效果
• 可折叠内容过渡效果
• Canvas 中的边缘动画
• 加载器旋转动画

参考资料

• 对话组件
• 提示输入组件
• 工作流组件
• 可视化组件