/ai-elements

name: ai-elements
description: Vercel AI Elements for workflow UI components. Use when building chat interfaces, displaying tool execution, showing reasoning/thinking, or creating job queues. Triggers on ai-elements, Queue, Confirmation, Tool, Reasoning, Shimmer, Loader, Message, Conversation, PromptInput.

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:

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

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

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

Gates (before relying on examples)

Use this sequence when adding or wiring AI Elements so setup is checkable, not assumed.

1. **Install each component** — Run `npx shadcn@latest add https://ai-elements.vercel.app/r/[component-name]` for every component you need.

• **Pass:** The command completes successfully and a file for that component exists under your project’s `components/ai-elements/` (or the directory `components.json` uses for those additions).

2. **Align import paths** — Every `import … from "@/components/ai-elements/..."` must match your repo’s actual alias and folder layout.

• **Pass:** Each import resolves to a file on disk (IDE navigation or build/`tsc` shows no “cannot find module” for those paths).

3. **Match `Tool` / `Confirmation` states to your AI SDK** — State strings (including approval-related states) depend on the installed `ai` package major/version.

• **Pass:** The states you pass to `ToolHeader`, `Tool`, or `Confirmation` are listed in the AI SDK version you have installed (docs or exported types), not copied from memory alone.

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](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](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](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](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:

<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

Controlled vs Uncontrolled

Components support both controlled and uncontrolled patterns:

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

1. `input-streaming`: Parameters being received 2. `input-available`: Ready to execute 3. `approval-requested`: Awaiting user approval (SDK v6) 4. `approval-responded`: User responded (SDK v6) 5. `output-available`: Execution completed 6. `output-error`: Execution failed 7. `output-denied`: Approval denied

Queue Patterns

Queue components support hierarchical organization:

<Queue>
  <QueueSection defaultOpen={true}>
    <QueueSectionTrigger>
      <QueueSectionLabel count={3} label="tasks" icon={<Icon />} />
    </QueueSectionTrigger>
    <QueueSect