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.
Installation
Install via shadcn registry:
CODEBLOCK0
Import Pattern: Components are imported from individual files, not a barrel export:
CODEBLOCK1
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.
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.
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.
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.
Integration with 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
Key Design Patterns
Component Composition
AI Elements follows a composition-first approach where larger components are built from smaller primitives:
CODEBLOCK2
Context-Based State
Many components use React Context for state management:
- -
PromptInputProvider for global input state - INLINECODE1 for alternative response navigation
- INLINECODE2 for approval workflow state
- INLINECODE3 for collapsible thinking state
Controlled vs Uncontrolled
Components support both controlled and uncontrolled patterns:
CODEBLOCK3
Tool State Machine
The Tool component follows the Vercel AI SDK's state machine:
- 1.
input-streaming: Parameters being received - INLINECODE5 : Ready to execute
- INLINECODE6 : Awaiting user approval (SDK v6)
- INLINECODE7 : User responded (SDK v6)
- INLINECODE8 : Execution completed
- INLINECODE9 : Execution failed
- INLINECODE10 : Approval denied
Queue Patterns
Queue components support hierarchical organization:
CODEBLOCK4
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
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
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
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
TypeScript Types
All components are fully typed with TypeScript:
CODEBLOCK5
Common Use Cases
Chat Interface
Combine Conversation, Message, and PromptInput for a complete chat UI:
CODEBLOCK6
Tool Execution Display
Show tool execution with expandable details:
CODEBLOCK7
Approval Workflow
Request user confirmation before executing actions:
CODEBLOCK8
Job Queue Management
Display task lists with completion status:
CODEBLOCK9
Accessibility
Components include accessibility features:
- - ARIA labels and roles
- Keyboard navigation support
- Screen reader announcements
- Focus management
- Semantic HTML elements
Animation
Many components use Framer Motion for smooth animations:
- - Shimmer effect for loading states
- Collapsible content transitions
- Edge animations in Canvas
- Loader spinner rotation
References
AI Elements
AI Elements 是一个全面的 React 组件库，用于构建 AI 驱动的用户界面。该库提供了 30 多个专门为聊天界面、工具执行可视化、推理显示和工作流管理设计的组件。
安装
通过 shadcn 注册表安装：
bash
npx shadcn@latest add https://ai-elements.vercel.app/r/[component-name]
导入模式：组件从单个文件导入，而非批量导出：
tsx
// 正确 - 从特定文件导入
import { Conversation } from @/components/ai-elements/conversation;
import { Message } from @/components/ai-elements/message;
import { PromptInput } from @/components/ai-elements/prompt-input;
// 错误 - 没有批量导出
import { Conversation, Message } from @/components/ai-elements;
组件分类
对话组件
用于显示聊天式界面的组件，支持消息、附件和自动滚动行为。
- - 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 采用组合优先的方法，较大的组件由较小的原语构建：
tsx
基于上下文的状态管理
许多组件使用 React Context 进行状态管理：
- - PromptInputProvider 用于全局输入状态
- MessageBranch 用于备选回复导航
- Confirmation 用于审批工作流状态
- Reasoning 用于可折叠思考状态
受控与非受控
组件支持受控和非受控模式：
tsx
// 非受控（自管理状态）
// 受控（外部状态）
工具状态机
Tool 组件遵循 Vercel AI SDK 的状态机：
- 1. input-streaming：正在接收参数
- input-available：准备执行
- approval-requested：等待用户批准（SDK v6）
- approval-responded：用户已响应（SDK v6）
- output-available：执行完成
- output-error：执行失败
- output-denied：批准被拒绝
队列模式
队列组件支持层级组织：
tsx
} />
Task description
自动滚动行为
Conversation 组件使用 use-stick-to-bottom 钩子实现智能自动滚动：
- - 新消息到达时自动滚动到底部
- 用户向上滚动时暂停自动滚动
- 不在底部时提供滚动到底部按钮
- 支持平滑和即时滚动模式
文件附件处理
PromptInput 提供全面的文件处理功能：
- - 拖放支持（本地或全局）
- 粘贴图片/文件支持
- 文件类型验证（accept 属性）
- 文件大小限制（maxFileSize 属性）
- 最大文件数量（maxFiles 属性）
- 图片预览，文件图标
- 提交时自动将 blob URL 转换为 data URL
语音输入
PromptInputSpeechButton 使用 Web Speech API 进行语音输入：
- - 基于浏览器的语音识别
- 连续识别模式
- 支持中间结果
- 自动将文本插入文本区域
- 录制期间的视觉反馈
推理自动折叠
Reasoning 组件提供自动折叠行为：
- - 流式传输开始时自动打开
- 流式传输结束后 1 秒关闭
- 以秒为单位跟踪思考时长
- 流式传输期间显示带闪烁效果的思考中...
- 完成时显示思考了 N 秒
TypeScript 类型
所有组件都使用 TypeScript 进行完整类型定义：
typescript
import type { ToolUIPart, FileUIPart, UIMessage } from ai;
type ToolProps = ComponentProps;
type QueueItemProps = ComponentProps;
type MessageAttachmentProps = HTMLAttributes & {
data: FileUIPart;
onRemove?: () => void;
};
常见用例
聊天界面
组合 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;
{messages.map(msg => (
{msg.content}
))}
attachments.openFileDialog()}>
工具执行显示
显示带有可展开详情的工具执行：
tsx
import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from @/components/ai-elements/tool;
{toolInvocations.map(tool => (
title={tool.toolName}
type={tool-call-${tool.toolName}}
state={tool.state}
/>
{tool.result && (
)}
))}
审批工作流
在执行操作前请求用户确认：
tsx
import {
Confirmation,
ConfirmationTitle,
ConfirmationRequest,
ConfirmationActions,
ConfirmationAction,
ConfirmationAccepted,
ConfirmationRejected
} from @/components/ai-elements/confirmation;
