ai-elements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Elements

AI Elements is a comprehensive React component library for building AI-powered user interfaces. The library provides 30+ components specifically designed for chat interfaces, tool execution visualization, reasoning displays, and workflow management.

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

Installation

安装

Install via shadcn registry:

bash

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

Import Pattern: Components are imported from individual files, not a barrel export:

tsx

// 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";

通过shadcn注册表安装：

bash

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

导入模式：组件需从单独文件导入，不支持桶式导出：

tsx

// 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";

Component Categories

组件分类

Conversation Components

对话组件

Components for displaying chat-style interfaces with messages, attachments, and auto-scrolling behavior.

Conversation: Container with auto-scroll capabilities
Message: Individual message display with role-based styling
MessageAttachment: File and image attachments
MessageBranch: Alternative response navigation

See references/conversation.md for details.

用于展示包含消息、附件和自动滚动行为的聊天式界面。

Conversation：具备自动滚动能力的容器
Message：基于角色样式的单个消息展示组件
MessageAttachment：文件和图片附件组件
MessageBranch：备选回复导航组件

详情请参阅 references/conversation.md。

Prompt Input Components

提示输入组件

Advanced text input with file attachments, drag-and-drop, speech input, and state management.

PromptInput: Form container with file handling
PromptInputTextarea: Auto-expanding textarea
PromptInputSubmit: Status-aware submit button
PromptInputAttachments: File attachment display
PromptInputProvider: Global state management

See references/prompt-input.md for details.

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

PromptInput：包含文件处理的表单容器
PromptInputTextarea：自动扩展的文本域
PromptInputSubmit：状态感知的提交按钮
PromptInputAttachments：文件附件展示组件
PromptInputProvider：全局状态管理组件

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

Workflow Components

工作流组件

Components for displaying job queues, tool execution, and approval workflows.

Queue: Job queue container
QueueItem: Individual queue items with status
Tool: Tool execution display with collapsible states
Confirmation: Approval workflow component
Reasoning: Collapsible thinking/reasoning display

See references/workflow.md for details.

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

Queue：任务队列容器
QueueItem：包含状态的单个队列项
Tool：可折叠状态的工具执行展示组件
Confirmation：审批工作流组件
Reasoning：可折叠的推理/思考过程展示组件

详情请参阅 references/workflow.md。

Visualization Components

可视化组件

ReactFlow-based components for workflow visualization and custom node types.

Canvas: ReactFlow wrapper with aviation-specific defaults
Node: Custom node component with handles
Edge: Temporary and Animated edge types
Controls, Panel, Toolbar: Navigation and control elements

See references/visualization.md for details.

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

Canvas：带有航空领域默认配置的ReactFlow包装器
Node：带有手柄的自定义节点组件
Edge：临时和动画化的连线类型
Controls, Panel, Toolbar：导航和控制元素

详情请参阅 references/visualization.md。

Integration with shadcn/ui

与shadcn/ui的集成

AI Elements is built on top of shadcn/ui and integrates seamlessly with its theming system:

Uses shadcn/ui's design tokens (colors, spacing, typography)
Respects light/dark mode via CSS variables
Compatible with shadcn/ui components (Button, Card, Collapsible, etc.)
Follows shadcn/ui's component composition patterns

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

使用shadcn/ui的设计令牌（颜色、间距、排版）
通过CSS变量适配明暗模式
与shadcn/ui组件（Button、Card、Collapsible等）兼容
遵循shadcn/ui的组件组合模式

Key Design Patterns

核心设计模式

Component Composition

组件组合

AI Elements follows a composition-first approach where larger components are built from smaller primitives:

tsx

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

AI Elements 采用组合优先的设计方式，大型组件由小型基础组件构建而成：

tsx

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

Context-Based State

基于上下文的状态管理

Many components use React Context for state management:

```
PromptInputProvider
```
for global input state
```
MessageBranch
```
for alternative response navigation
```
Confirmation
```
for approval workflow state
```
Reasoning
```
for collapsible thinking state

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

```
PromptInputProvider
```
：用于全局输入状态
```
MessageBranch
```
：用于备选回复导航
```
Confirmation
```
：用于审批工作流状态
```
Reasoning
```
：用于可折叠的思考状态

Controlled vs Uncontrolled

受控与非受控模式

Components support both controlled and uncontrolled patterns:

tsx

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

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

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

tsx

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

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

Tool State Machine

工具状态机

The Tool component follows the Vercel AI SDK's state machine:

```
input-streaming
```
: Parameters being received
```
input-available
```
: Ready to execute
```
approval-requested
```
: Awaiting user approval (SDK v6)
```
approval-responded
```
: User responded (SDK v6)
```
output-available
```
: Execution completed
```
output-error
```
: Execution failed
```
output-denied
```
: Approval denied

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

```
input-streaming
```
：参数接收中
```
input-available
```
：准备执行
```
approval-requested
```
：等待用户审批（SDK v6）
```
approval-responded
```
：用户已回复（SDK v6）
```
output-available
```
：执行完成
```
output-error
```
：执行失败
```
output-denied
```
：审批被拒绝

Queue Patterns

队列模式

Queue components support hierarchical organization:

tsx

<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>

队列组件支持层级化组织：

tsx

<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>

Auto-Scroll Behavior

自动滚动行为

The Conversation component uses the

use-stick-to-bottom

hook for intelligent auto-scrolling:

Automatically scrolls to bottom when new messages arrive
Pauses auto-scroll when user scrolls up
Provides scroll-to-bottom button when not at bottom
Supports smooth and instant scroll modes

Conversation组件使用

use-stick-to-bottom

钩子实现智能自动滚动：

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

File Attachment Handling

文件附件处理

PromptInput provides comprehensive file handling:

Drag-and-drop support (local or global)
Paste image/file support
File type validation (accept prop)
File size limits (maxFileSize prop)
Maximum file count (maxFiles prop)
Preview for images, icons for files
Automatic blob URL to data URL conversion on submit

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

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

Speech Input

语音输入

The PromptInputSpeechButton uses the Web Speech API for voice input:

Browser-based speech recognition
Continuous recognition mode
Interim results support
Automatic text insertion into textarea
Visual feedback during recording

PromptInputSpeechButton使用Web Speech API实现语音输入：

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

Reasoning Auto-Collapse

推理内容自动折叠

The Reasoning component provides auto-collapse behavior:

Opens automatically when streaming starts
Closes 1 second after streaming ends
Tracks thinking duration in seconds
Displays "Thinking..." with shimmer effect during streaming
Shows "Thought for N seconds" when complete

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

流式传输开始时自动展开
流式传输结束1秒后自动关闭
跟踪思考持续时间（秒）
流式传输期间显示“思考中...”及微光效果
完成后显示“思考了N秒”

TypeScript Types

TypeScript类型

All components are fully typed with 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;
};

所有组件均已完全支持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;
};

Common Use Cases

常见使用场景

Chat Interface

聊天界面

Combine Conversation, Message, and PromptInput for a complete chat UI:

tsx

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>

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

tsx

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>

Tool Execution Display

工具执行展示

Show tool execution with expandable details:

tsx

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>
))}

展示工具执行过程及可展开的详情：

tsx

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>
))}

Approval Workflow

审批工作流

Request user confirmation before executing actions:

tsx

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>

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

tsx

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>

Job Queue Management

任务队列管理

Display task lists with completion status:

tsx

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>

展示包含完成状态的任务列表：

tsx

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>

Accessibility

可访问性

Components include accessibility features:

ARIA labels and roles
Keyboard navigation support
Screen reader announcements
Focus management
Semantic HTML elements

组件包含以下可访问性功能：

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

Animation

动画效果

Many components use Framer Motion for smooth animations:

Shimmer effect for loading states
Collapsible content transitions
Edge animations in Canvas
Loader spinner rotation

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

加载状态的微光效果
可折叠内容的过渡动画
Canvas中的连线动画
加载器的旋转动画

References

参考资料

Conversation Components
Prompt Input Components
Workflow Components
Visualization Components

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