Ai Elements

Agent

A composable component for displaying AI agent configuration with model, instructions, tools, and output schema.

The Agent component displays an interface for showing AI agent configuration details. It's designed to represent a configured agent from the AI SDK, showing the agent's model, system instructions, available tools (with expandable input schemas), and output schema.

See scripts/agent.tsx for this example.

Installation

npx ai-elements@latest add agent

Usage with AI SDK

Display an agent's configuration alongside your chat interface. Tools are displayed in an accordion where clicking the description expands to show the input schema.

```tsx title="app/page.tsx" "use client";

import { tool } from "ai"; import { z } from "zod"; import { Agent, AgentContent, AgentHeader, AgentInstructions, AgentOutput, AgentTool, AgentTools, } from "@/components/ai-elements/agent";

const webSearch = tool({ description: "Search the web for information", inputSchema: z.object({ query: z.string().describe("The search query"), }), });

const readUrl = tool({ description: "Read and parse content from a URL", inputSchema: z.object({ url: z.string().url().describe("The URL to read"), }), });

const outputSchema = z.object({ sentiment: z.enum(['positive', 'negative', 'neutral']), score: z.number(), summary: z.string(), });

export default function Page() { return ( <Agent> <AgentHeader name="Sentiment Analyzer" model="anthropic/claude-sonnet-4-6" /> <AgentContent> <AgentInstructions> Analyze the sentiment of the provided text and return a structured analysis with sentiment classification, confidence score, and summary. </AgentInstructions> <AgentTools> <AgentTool tool={webSearch} value="web_search" /> <AgentTool tool={readUrl} value="read_url" /> </AgentTools> <AgentOutput schema={outputSchema} /> </AgentContent> </Agent> ); }

## Features

- Model badge in header
- Instructions rendered as markdown
- Tools displayed as accordion items with expandable input schemas
- Output schema display with syntax highlighting
- Composable structure for flexible layouts
- Works with AI SDK `Tool` type

## Props

### `<Agent />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any props are spread to the root div. |

### `<AgentHeader />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | Required | The name of the agent. |
| `model` | `string` | - | The model identifier (e.g.  |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the container div. |

### `<AgentContent />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the container div. |

### `<AgentInstructions />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `string` | Required | The instruction text. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the container div. |

### `<AgentTools />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof Accordion>` | - | Any other props are spread to the Accordion component. |

### `<AgentTool />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tool` | `Tool` | Required | The tool object from the AI SDK containing description and inputSchema. |
| `value` | `string` | Required | Unique identifier for the accordion item. |
| `...props` | `React.ComponentProps<typeof AccordionItem>` | - | Any other props are spread to the AccordionItem component. |

### `<AgentOutput />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `schema` | `string` | Required | The output schema as a string (displayed with syntax highlighting). |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the container div. |

Artifact

A container component for displaying generated content like code, documents, or other outputs with built-in actions.

The Artifact component provides a structured container for displaying generated content like code, documents, or other outputs with built-in header actions.

See scripts/artifact.tsx for this example.

Installation

npx ai-elements@latest add artifact

Features

• Structured container with header and content areas
• Built-in header with title and description support
• Flexible action buttons with tooltips
• Customizable styling for all subcomponents
• Support for close buttons and action groups
• Clean, modern design with border and shadow
• Responsive layout that adapts to content
• TypeScript support with proper type definitions
• Composable architecture for maximum flexibility

Examples

With Code Display

See scripts/artifact.tsx for this example.

Props

<Artifact />

<ArtifactHeader />

<ArtifactTitle />

<ArtifactDescription />

<ArtifactActions />

<ArtifactAction />

<ArtifactClose />

<ArtifactContent />

Attachments

A flexible, composable attachment component for displaying files, images, videos, audio, and source documents.

The Attachment component provides a unified way to display file attachments and source documents with multiple layout variants.

See scripts/attachments.tsx for this example.

Installation

npx ai-elements@latest add attachments

Usage with AI SDK

Display user-uploaded files in chat messages or input areas.

```tsx title="app/page.tsx" "use client";

import { Attachments, Attachment, AttachmentPreview, AttachmentInfo, AttachmentRemove, } from "@/components/ai-elements/attachments"; import type { FileUIPart } from "ai";

interface MessageProps { attachments: (FileUIPart & { id: string })[]; onRemove?: (id: string) => void; }

const MessageAttachments = ({ attachments, onRemove }: MessageProps) => ( <Attachments variant="grid"> {attachments.map((file) => ( <Attachment key={file.id} data={file} onRemove={onRemove ? () => onRemove(file.id) : undefined} > <AttachmentPreview /> <AttachmentRemove /> </Attachment> ))} </Attachments> );

export default MessageAttachments;

## Features

- Three display variants: grid (thumbnails), inline (badges), and list (rows)
- Supports both FileUIPart and SourceDocumentUIPart from the AI SDK
- Automatic media type detection (image, video, audio, document, source)
- Hover card support for inline previews
- Remove button with customizable callback
- Composable architecture for maximum flexibility
- Accessible with proper ARIA labels
- TypeScript support with exported utility functions

## Examples

### Grid Variant

Best for displaying attachments in messages with visual thumbnails.

See `scripts/attachments.tsx` for this example.

### Inline Variant

Best for compact badge-style display in input areas with hover previews.

See `scripts/attachments-inline.tsx` for this example.

### List Variant

Best for file lists with full metadata display.

See `scripts/attachments-list.tsx` for this example.

## Props

### `<Attachments />`

Container component that sets the layout variant.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `variant` | `unknown` | - | The display layout variant. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the underlying div element. |

### `<Attachment />`

Individual attachment item wrapper.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `unknown` | - | The attachment data (FileUIPart or SourceDocumentUIPart with id). |
| `onRemove` | `() => void` | - | Callback fired when the remove button is clicked. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the underlying div element. |

### `<AttachmentPreview />`

Displays the media preview (image, video, or icon).

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `fallbackIcon` | `React.ReactNode` | - | Custom icon to display when no preview is available. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the underlying div element. |

### `<AttachmentInfo />`

Displays the filename and optional media type.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showMediaType` | `boolean` | `false` | Whether to show the media type below the filename. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the underlying div element. |

### `<AttachmentRemove />`

Remove button that appears on hover.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | - | Screen reader label for the button. |
| `...props` | `React.ComponentProps<typeof Button>` | - | Spread to the underlying Button component. |

### `<AttachmentHoverCard />`

Wrapper for hover preview functionality.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `openDelay` | `number` | `0` | Delay in ms before opening the hover card. |
| `closeDelay` | `number` | `0` | Delay in ms before closing the hover card. |
| `...props` | `React.ComponentProps<typeof HoverCard>` | - | Spread to the underlying HoverCard component. |

### `<AttachmentHoverCardTrigger />`

Trigger element for the hover card.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof HoverCardTrigger>` | - | Spread to the underlying HoverCardTrigger component. |

### `<AttachmentHoverCardContent />`

Content displayed in the hover card.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `align` | `unknown` | - | Alignment of the hover card content. |
| `...props` | `React.ComponentProps<typeof HoverCardContent>` | - | Spread to the underlying HoverCardContent component. |

### `<AttachmentEmpty />`

Empty state component when no attachments are present.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Spread to the underlying div element. |

## Utility Functions

### `getMediaCategory(data)`

Returns the media category for an attachment.

import { getMediaCategory } from "@/components/ai-elements/attachments";

const category = getMediaCategory(attachment); // Returns: "image" | "video" | "audio" | "document" | "source" | "unknown"

### `getAttachmentLabel(data)`

Returns the display label for an attachment.

import { getAttachmentLabel } from "@/components/ai-elements/attachments";

const label = getAttachmentLabel(attachment); // Returns filename or fallback like "Image" or "Attachment"

Audio Player

A composable audio player component built on media-chrome, with shadcn styling and flexible controls.

The AudioPlayer component provides a flexible and customizable audio playback interface built on top of media-chrome. It features a composable architecture that allows you to build audio experiences with custom controls, metadata display, and seamless integration with AI-generated audio content.

See scripts/audio-player.tsx for this example.

Installation

npx ai-elements@latest add audio-player

Features

• Built on media-chrome for reliable audio playback
• Fully composable architecture with granular control components
• ButtonGroup integration for cohesive control layout
• Individual control components (play, seek, volume, etc.)
• Flexible layout with customizable control bars
• CSS custom properties for deep theming
• Shadcn/ui Button component styling
• Responsive design that works across devices
• Full TypeScript support with proper types for all components

Variants

AI SDK Speech Result

The AudioPlayer component can be used to play audio from an AI SDK Speech Result.

See scripts/audio-player.tsx for this example.

Remote Audio

The AudioPlayer component can be used to play remote audio files.

See scripts/audio-player-remote.tsx for this example.

Props

<AudioPlayer />

Root MediaController component. Accepts all MediaController props except audio (which is set to true by default).

<AudioPlayerElement />

The audio element that contains the media source. Accepts either a remote URL or AI SDK Speech Result data.

<AudioPlayerControlBar />

Container for control buttons, wraps children in a ButtonGroup.

<AudioPlayerPlayButton />

Play/pause button wrapped in a shadcn Button component.

<AudioPlayerSeekBackwardButton />

Seek backward button wrapped in a shadcn Button component.

<AudioPlayerSeekForwardButton />

Seek forward button wrapped in a shadcn Button component.

<AudioPlayerTimeDisplay />

Displays the current playback time, wrapped in ButtonGroupText.

<AudioPlayerTimeRange />

Seek slider for controlling playback position, wrapped in ButtonGroupText.

<AudioPlayerDurationDisplay />

Displays the total duration of the audio, wrapped in ButtonGroupText.

<AudioPlayerMuteButton />

Mute/unmute button, wrapped in ButtonGroupText.

<AudioPlayerVolumeRange />

Volume slider control, wrapped in ButtonGroupText.

Canvas

A React Flow-based canvas component for building interactive node-based interfaces.

The Canvas component provides a React Flow-based canvas for building interactive node-based interfaces. It comes pre-configured with sensible defaults for AI applications, including panning, zooming, and selection behaviors.

Installation

npx ai-elements@latest add canvas

Features

• Pre-configured React Flow canvas with AI-optimized defaults
• Pan on scroll enabled for intuitive navigation
• Selection on drag for multi-node operations
• Customizable background color using CSS variables
• Delete key support (Backspace and Delete keys)
• Auto-fit view to show all nodes
• Disabled double-click zoom for better UX
• Disabled pan on drag to prevent accidental canvas movement
• Fully compatible with React Flow props and API

Props

<Canvas />

Chain of Thought

A collapsible component that visualizes AI reasoning steps with support for search results, images, and step-by-step progress indicators.

The ChainOfThought component provides a visual representation of an AI's reasoning process, showing step-by-step thinking with support for search results, images, and progress indicators. It helps users understand how AI arrives at conclusions.

See scripts/chain-of-thought.tsx for this example.

Installation

npx ai-elements@latest add chain-of-thought

Features

• Collapsible interface with smooth animations powered by Radix UI
• Step-by-step visualization of AI reasoning process
• Support for different step statuses (complete, active, pending)
• Built-in search results display with badge styling
• Image support with captions for visual content
• Custom icons for different step types
• Context-aware components using React Context API
• Fully typed with TypeScript
• Accessible with keyboard navigation support
• Responsive design that adapts to different screen sizes
• Smooth fade and slide animations for content transitions
• Composable architecture for flexible customization

Props

<ChainOfThought />

<ChainOfThoughtHeader />

<ChainOfThoughtStep />

<ChainOfThoughtSearchResults />

<ChainOfThoughtSearchResult />

<ChainOfThoughtContent />

<ChainOfThoughtImage />

Chatbot Components

Detailed reference for AI Elements chatbot components.

Conversation

Auto-scrolling chat container using use-stick-to-bottom.

import {
  Conversation,
  ConversationContent,
  ConversationScrollButton,
  ConversationEmptyState,
} from '@/components/ai-elements/conversation';

<Conversation>
  <ConversationContent>
    {messages.length === 0 ? (
      <ConversationEmptyState
        title="Start a conversation"
        description="Ask me anything!"
        icon={<MessageIcon />}
      />
    ) : (
      messages.map((msg) => <Message key={msg.id} ... />)
    )}
  </ConversationContent>
  <ConversationScrollButton />
</Conversation>

Props

Message

Single message with role-based styling.

import {
  Message,
  MessageContent,
  MessageResponse,
  MessageActions,
  MessageAction,
  MessageAttachment,
  MessageAttachments,
} from '@/components/ai-elements/message';

<Message from="assistant">
  <MessageContent>
    <MessageResponse>{text}</MessageResponse>
  </MessageContent>
  <MessageActions>
    <MessageAction label="Copy" onClick={() => navigator.clipboard.writeText(text)}>
      <CopyIcon className="size-3" />
    </MessageAction>
    <MessageAction label="Retry" onClick={() => regenerate()}>
      <RefreshCcwIcon className="size-3" />
    </MessageAction>
  </MessageActions>
</Message>

Props

Message Branching

For multiple response variations (e.g., regenerated responses):

import {
  MessageBranch,
  MessageBranchContent,
  MessageBranchSelector,
  MessageBranchPrevious,
  MessageBranchNext,
  MessageBranchPage,
} from '@/components/ai-elements/message';

<MessageBranch defaultBranch={0} onBranchChange={(i) => console.log(i)}>
  <MessageBranchContent>
    <Message from="assistant">Response 1</Message>
    <Message from="assistant">Response 2</Message>
    <Message from="assistant">Response 3</Message>
  </MessageBranchContent>
  <MessageBranchSelector from="assistant">
    <MessageBranchPrevious />
    <MessageBranchPage /> {/* Shows "1 of 3" */}
    <MessageBranchNext />
  </MessageBranchSelector>
</MessageBranch>

PromptInput

Rich input with file attachments, model picker, and action menu.

Basic Usage

import {
  PromptInput,
  PromptInputBody,
  PromptInputTextarea,
  PromptInputFooter,
  PromptInputSubmit,
  type PromptInputMessage,
} from '@/components/ai-elements/prompt-input';

const handleSubmit = (message: PromptInputMessage) => {
  sendMessage({
    text: message.text,
    files: message.files,
  });
};

<PromptInput onSubmit={handleSubmit}>
  <PromptInputBody>
    <PromptInputTextarea value={input} onChange={(e) => setInput(e.target.value)} />
  </PromptInputBody>
  <PromptInputFooter>
    <PromptInputSubmit status={status} />
  </PromptInputFooter>
</PromptInput>

Full Featured

import {
  PromptInput,
  PromptInputHeader,
  PromptInputBody,
  PromptInputFooter,
  PromptInputTextarea,
  PromptInputTools,
  PromptInputButton,
  PromptInputSubmit,
  PromptInputAttachments,
  PromptInputAttachment,
  PromptInputActionMenu,
  PromptInputActionMenuTrigger,
  PromptInputActionMenuContent,
  PromptInputActionAddAttachments,
  PromptInputSelect,
  PromptInputSelectTrigger,
  PromptInputSelectValue,
  PromptInputSelectContent,
  PromptInputSelectItem,
  PromptInputSpeechButton,
} from '@/components/ai-elements/prompt-input';

<PromptInput
  onSubmit={handleSubmit}
  globalDrop        // Accept drops anywhere on document
  multiple          // Allow multiple files
  accept="image/*"  // Only images
  maxFiles={5}
  maxFileSize={10 * 1024 * 1024} // 10MB
  onError={(err) => console.error(err.code, err.message)}
>
  <PromptInputHeader>
    <PromptInputAttachments>
      {(attachment) => <PromptInputAttachment data={attachment} />}
    </PromptInputAttachments>
  </PromptInputHeader>

  <PromptInputBody>
    <PromptInputTextarea
      value={input}
      onChange={(e) => setInput(e.target.value)}
      placeholder="What would you like to know?"
    />
  </PromptInputBody>

  <PromptInputFooter>
    <PromptInputTools>
      {/* Action Menu */}
      <PromptInputActionMenu>
        <PromptInputActionMenuTrigger />
        <PromptInputActionMenuContent>
          <PromptInputActionAddAttachments label="Add photos or files" />
        </PromptInputActionMenuContent>
      </PromptInputActionMenu>

      {/* Custom Toggle Button */}
      <PromptInputButton
        variant={webSearch ? 'default' : 'ghost'}
        onClick={() => setWebSearch(!webSearch)}
      >
        <GlobeIcon size={16} />
        <span>Search</span>
      </PromptInputButton>

      {/* Model Selector */}
      <PromptInputSelect value={model} onValueChange={setModel}>
        <PromptInputSelectTrigger>
          <PromptInputSelectValue />
        </PromptInputSelectTrigger>
        <PromptInputSelectContent>
          {models.map((m) => (
            <PromptInputSelectItem key={m.value} value={m.value}>
              {m.name}
            </PromptInputSelectItem>
          ))}
        </PromptInputSelectContent>
      </PromptInputSelect>

      {/* Speech Input */}
      <PromptInputSpeechButton textareaRef={textareaRef} />
    </PromptInputTools>

    <PromptInputSubmit status={status} />
  </PromptInputFooter>
</PromptInput>

Props

PromptInputMessage Type

type PromptInputMessage = {
  text: string;
  files: FileUIPart[];
};

Keyboard Shortcuts

• Enter - Submit (unless Shift held or composing)
• Backspace - Remove last attachment when textarea empty
• Paste - Paste images/files from clipboard

Reasoning

Collapsible thinking/reasoning display with auto-collapse.

import {
  Reasoning,
  ReasoningTrigger,
  ReasoningContent,
} from '@/components/ai-elements/reasoning';

<Reasoning
  isStreaming={status === 'streaming'}
  defaultOpen={true}
  duration={10} // seconds
>
  <ReasoningTrigger
    getThinkingMessage={(isStreaming, duration) =>
      isStreaming ? 'Thinking...' : `Thought for ${duration}s`
    }
  />
  <ReasoningContent>{reasoningText}</ReasoningContent>
</Reasoning>

Props

Behavior

• Opens automatically when isStreaming=true
• Auto-closes 1000ms after streaming ends (one-time only)
• Shows shimmer animation while streaming

Sources

Collapsible citation/reference display.

import {
  Sources,
  SourcesTrigger,
  SourcesContent,
  Source,
} from '@/components/ai-elements/sources';

const sourceUrls = message.parts.filter((p) => p.type === 'source-url');

{sourceUrls.length > 0 && (
  <Sources>
    <SourcesTrigger count={sourceUrls.length} />
    <SourcesContent>
      {sourceUrls.map((part, i) => (
        <Source key={i} href={part.url} title={part.title} />
      ))}
    </SourcesContent>
  </Sources>
)}

Props

Tool

Tool execution visualization with status indicators.

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

{part.type.startsWith('tool-') && (
  <Tool>
    <ToolHeader
      title={part.toolName}
      type={part.type}
      state={part.state}
    />
    <ToolContent>
      <ToolInput input={part.input} />
      <ToolOutput output={part.output} errorText={part.errorText} />
    </ToolContent>
  </Tool>
)}

Tool States

ChainOfThought

Step-by-step reasoning breakdown.

import {
  ChainOfThought,
  ChainOfThoughtHeader,
  ChainOfThoughtContent,
  ChainOfThoughtStep,
  ChainOfThoughtSearchResults,
  ChainOfThoughtImage,
} from '@/components/ai-elements/chain-of-thought';

<ChainOfThought defaultOpen={false}>
  <ChainOfThoughtHeader>View reasoning steps</ChainOfThoughtHeader>
  <ChainOfThoughtContent>
    <ChainOfThoughtStep
      icon={SearchIcon}
      label="Searching web"
      description="Found 5 results"
      status="complete"
    />
    <ChainOfThoughtStep
      icon={BrainIcon}
      label="Analyzing results"
      status="active"
    />
    <ChainOfThoughtStep
      icon={PenIcon}
      label="Writing response"
      status="pending"
    />
    <ChainOfThoughtSearchResults>
      <Badge>Result 1</Badge>
      <Badge>Result 2</Badge>
    </ChainOfThoughtSearchResults>
  </ChainOfThoughtContent>
</ChainOfThought>

Step Status

• complete - Green check, completed step
• active - Pulsing indicator, current step
• pending - Gray, waiting step

Loader

Loading indicator for submitted state.

import { Loader } from '@/components/ai-elements/loader';

{status === 'submitted' && <Loader />}

InlineCitation

Inline citation badge with hover card and carousel for multiple sources.

import {
  InlineCitation,
  InlineCitationText,
  InlineCitationCard,
  InlineCitationCardTrigger,
  InlineCitationCardBody,
  InlineCitationCarousel,
  InlineCitationCarouselHeader,
  InlineCitationCarouselPrev,
  InlineCitationCarouselIndex,
  InlineCitationCarouselNext,
  InlineCitationCarouselContent,
  InlineCitationCarouselItem,
  InlineCitationSource,
  InlineCitationQuote,
} from '@/components/ai-elements/inline-citation';

<InlineCitation>
  <InlineCitationText>cited text here</InlineCitationText>
  <InlineCitationCard>
    <InlineCitationCardTrigger sources={['https://example.com']} />
    <InlineCitationCardBody>
      <InlineCitationCarousel>
        <InlineCitationCarouselHeader>
          <InlineCitationCarouselPrev />
          <InlineCitationCarouselIndex />
          <InlineCitationCarouselNext />
        </InlineCitationCarouselHeader>
        <InlineCitationCarouselContent>
          <InlineCitationCarouselItem>
            <InlineCitationSource
              title="Source Title"
              url="https://example.com"
              description="Source description..."
            />
            <InlineCitationQuote>Quoted text from source</InlineCitationQuote>
          </InlineCitationCarouselItem>
        </InlineCitationCarouselContent>
      </InlineCitationCarousel>
    </InlineCitationCardBody>
  </InlineCitationCard>
</InlineCitation>

Props

Plan

Collapsible plan card with streaming shimmer effect on title/description.

import {
  Plan,
  PlanHeader,
  PlanTitle,
  PlanDescription,
  PlanAction,
  PlanContent,
  PlanFooter,
  PlanTrigger,
} from '@/components/ai-elements/plan';

<Plan isStreaming={status === 'streaming'} defaultOpen>
  <PlanHeader>
    <div>
      <PlanTitle>Implementation Plan</PlanTitle>
      <PlanDescription>Steps to complete the task</PlanDescription>
    </div>
    <PlanAction>
      <PlanTrigger />
    </PlanAction>
  </PlanHeader>
  <PlanContent>
    <ul>
      <li>Step 1: Research</li>
      <li>Step 2: Design</li>
      <li>Step 3: Implement</li>
    </ul>
  </PlanContent>
  <PlanFooter>
    <Button>Execute Plan</Button>
  </PlanFooter>
</Plan>

Props

Task

Collapsible task breakdown display with file references.

import {
  Task,
  TaskTrigger,
  TaskContent,
  TaskItem,
  TaskItemFile,
} from '@/components/ai-elements/task';

<Task defaultOpen>
  <TaskTrigger title="Searching codebase..." />
  <TaskContent>
    <TaskItem>
      Found in <TaskItemFile>src/components/Button.tsx</TaskItemFile>
    </TaskItem>
    <TaskItem>
      Also referenced in <TaskItemFile>src/pages/index.tsx</TaskItemFile>
    </TaskItem>
  </TaskContent>
</Task>

Props

Queue

Todo/message queue display with sections for pending and completed items.

import {
  Queue,
  QueueSection,
  QueueSectionTrigger,
  QueueSectionLabel,
  QueueSectionContent,
  QueueList,
  QueueItem,
  QueueItemIndicator,
  QueueItemContent,
  QueueItemDescription,
  QueueItemActions,
  QueueItemAction,
  QueueItemAttachment,
  QueueItemImage,
  QueueItemFile,
} from '@/components/ai-elements/queue';

<Queue>
  <QueueSection>
    <QueueSectionTrigger>
      <QueueSectionLabel
        count={3}
        label="pending"
        icon={<ClockIcon className="size-4" />}
      />
    </QueueSectionTrigger>
    <QueueSectionContent>
      <QueueList>
        <QueueItem>
          <div className="flex items-center gap-2">
            <QueueItemIndicator />
            <QueueItemContent>Task description here</QueueItemContent>
          </div>
          <QueueItemDescription>Additional details</QueueItemDescription>
          <QueueItemAttachment>
            <QueueItemImage src="/image.png" />
            <QueueItemFile>document.pdf</QueueItemFile>
          </QueueItemAttachment>
          <QueueItemActions>
            <QueueItemAction onClick={() => {}}>
              <TrashIcon className="size-3" />
            </QueueItemAction>
          </QueueItemActions>
        </QueueItem>
      </QueueList>
    </QueueSectionContent>
  </QueueSection>
</Queue>

Props

Complete Chatbot Example

See SKILL.md for core integration pattern, or the full tutorial in the AI Elements documentation.

Checkpoint

A simple component for marking conversation history points and restoring the chat to a previous state.

The Checkpoint component provides a way to mark specific points in a conversation history and restore the chat to that state. Inspired by VSCode's Copilot checkpoint feature, it allows users to revert to an earlier conversation state while maintaining a clear visual separation between different conversation segments.

See scripts/checkpoint.tsx for this example.

Installation

npx ai-elements@latest add checkpoint

Features

• Simple flex layout with icon, trigger, and separator
• Visual separator line for clear conversation breaks
• Clickable restore button for reverting to checkpoint
• Customizable icon (defaults to BookmarkIcon)
• Keyboard accessible with proper ARIA labels
• Responsive design that adapts to different screen sizes
• Seamless light/dark theme integration

Usage with AI SDK

Build a chat interface with conversation checkpoints that allow users to restore to previous states.

Add the following component to your frontend:

```tsx title="app/page.tsx" "use client";

import { useState, Fragment } from "react"; import { useChat } from "@ai-sdk/react"; import { Checkpoint, CheckpointIcon, CheckpointTrigger, } from "@/components/ai-elements/checkpoint"; import { Message, MessageContent, MessageResponse, } from "@/components/ai-elements/message"; import { Conversation, ConversationContent, } from "@/components/ai-elements/conversation";

type CheckpointType = { id: string; messageIndex: number; timestamp: Date; messageCount: number; };

const CheckpointDemo = () => { const { messages, setMessages } = useChat(); const [checkpoints, setCheckpoints] = useState<CheckpointType[]>([]);

const createCheckpoint = (messageIndex: number) => { const checkpoint: CheckpointType = { id: nanoid(), messageIndex, timestamp: new Date(), messageCount: messageIndex + 1, }; setCheckpoints([...checkpoints, checkpoint]); };

const restoreToCheckpoint = (messageIndex: number) => { // Restore messages to checkpoint state setMessages(messages.slice(0, messageIndex + 1)); // Remove checkpoints after this point setCheckpoints(checkpoints.filter((cp) => cp.messageIndex <= messageIndex)); };

return ( <div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]"> <Conversation> <ConversationContent> {messages.map((message, index) => { const checkpoint = checkpoints.find( (cp) => cp.messageIndex === index );

return ( <Fragment key={message.id}> <Message from={message.role}> <MessageContent> <MessageResponse>{message.content}</MessageResponse> </MessageContent> </Message> {checkpoint && ( <Checkpoint> <CheckpointIcon /> <CheckpointTrigger onClick={() => restoreToCheckpoint(checkpoint.messageIndex) } > Restore checkpoint </CheckpointTrigger> </Checkpoint> )} </Fragment> ); })} </ConversationContent> </Conversation> </div> ); };

export default CheckpointDemo;

## Use Cases

### Manual Checkpoints

Allow users to manually create checkpoints at important conversation points:

<Button onClick={() => createCheckpoint(messages.length - 1)}> Create Checkpoint </Button>

### Automatic Checkpoints

Create checkpoints automatically after significant conversation milestones:

useEffect(() => { // Create checkpoint every 5 messages if (messages.length > 0 && messages.length % 5 === 0) { createCheckpoint(messages.length - 1); } }, [messages.length]);

### Branching Conversations

Use checkpoints to enable conversation branching where users can explore different conversation paths:

const restoreAndBranch = (messageIndex: number) => { // Save current branch const currentBranch = messages.slice(messageIndex + 1); saveBranch(currentBranch);

// Restore to checkpoint restoreToCheckpoint(messageIndex); };

## Props

### `<Checkpoint />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | The checkpoint icon and trigger components. Automatically includes a Separator at the end. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the root div. |

### `<CheckpointIcon />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | Custom icon content. If not provided, defaults to a BookmarkIcon from lucide-react. |
| `...props` | `LucideProps` | - | Any other props are spread to the BookmarkIcon component. |

### `<CheckpointTrigger />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | The text or content to display in the trigger button. |
| `variant` | `string` | - | The button variant style. |
| `size` | `string` | - | The button size. |
| `...props` | `React.ComponentProps<typeof Button>` | - | Any other props are spread to the underlying shadcn/ui Button component. |

Code Block

Provides syntax highlighting, line numbers, and copy to clipboard functionality for code blocks.

The CodeBlock component provides syntax highlighting, line numbers, and copy to clipboard functionality for code blocks. It's fully composable, allowing you to customize the header, actions, and content.

See scripts/code-block.tsx for this example.

Installation

npx ai-elements@latest add code-block

Usage

The CodeBlock is fully composable. Here's a basic example:

import {
  CodeBlock,
  CodeBlockActions,
  CodeBlockCopyButton,
  CodeBlockFilename,
  CodeBlockHeader,
  CodeBlockTitle,
} from "@/components/ai-elements/code-block";
import { FileIcon } from "lucide-react";

export const Example = () => (
  <CodeBlock code={code} language="typescript">
    <CodeBlockHeader>
      <CodeBlockTitle>
        <FileIcon size={14} />
        <CodeBlockFilename>example.ts</CodeBlockFilename>
      </CodeBlockTitle>
      <CodeBlockActions>
        <CodeBlockCopyButton />
      </CodeBlockActions>
    </CodeBlockHeader>
  </CodeBlock>
);

Features

• Syntax highlighting with Shiki
• Line numbers (optional)
• Copy to clipboard functionality
• Automatic light/dark theme switching via CSS variables
• Language selector for multi-language examples
• Fully composable architecture
• Accessible design

Examples

Dark Mode

To use the CodeBlock component in dark mode, wrap it in a div with the dark class.

See scripts/code-block-dark.tsx for this example.

Language Selector

Add a language selector to switch between different code implementations:

See scripts/code-block.tsx for this example.

Props

<CodeBlock />

<CodeBlockHeader />

Container for the header row. Uses flexbox with justify-between.

<CodeBlockTitle />

Left-aligned container for icon and filename. Uses flexbox with gap-2.

<CodeBlockFilename />

Displays the filename in monospace font.

<CodeBlockActions />

Right-aligned container for action buttons. Uses flexbox with gap-2.

<CodeBlockCopyButton />

<CodeBlockLanguageSelector />

Wrapper for the language selector. Extends shadcn/ui Select.

<CodeBlockLanguageSelectorTrigger />

Trigger button for the language selector dropdown. Pre-styled for code block header.

<CodeBlockLanguageSelectorValue />

Displays the selected language value.

<CodeBlockLanguageSelectorContent />

Dropdown content container. Defaults to align="end".

<CodeBlockLanguageSelectorItem />

Individual language option in the dropdown.

<CodeBlockContainer />

Low-level container component with performance optimizations (contentVisibility). Used internally by CodeBlock.

<CodeBlockContent />

Low-level component that handles syntax highlighting. Used internally by CodeBlock, but can be used directly for custom layouts.

Commit

Display commit information with hash, message, author, and file changes.

The Commit component displays commit details including hash, message, author, timestamp, and changed files.

See scripts/commit.tsx for this example.

Installation

npx ai-elements@latest add commit

Features

• Commit hash display with copy button
• Author avatar with initials
• Relative timestamp formatting
• Collapsible file changes list
• Color-coded file status (added/modified/deleted/renamed)
• Line additions/deletions count

File Status

Props

<Commit />

<CommitHeader />

<CommitAuthor />

<CommitAuthorAvatar />

<CommitInfo />

<CommitMessage />

<CommitMetadata />

<CommitHash />

<CommitSeparator />

<CommitTimestamp />

<CommitActions />

<CommitCopyButton />

<CommitContent />

<CommitFiles />

<CommitFile />

<CommitFileInfo />

<CommitFileStatus />

<CommitFileIcon />

<CommitFilePath />

<CommitFileChanges />

<CommitFileAdditions />

<CommitFileDeletions />

Confirmation

An alert-based component for managing tool execution approval workflows with request, accept, and reject states.

The Confirmation component provides a flexible system for displaying tool approval requests and their outcomes. Perfect for showing users when AI tools require approval before execution, and displaying the approval status afterward.

See scripts/confirmation.tsx for this example.

Installation

npx ai-elements@latest add confirmation

Usage with AI SDK

Build a chat UI with tool approval workflow where dangerous tools require user confirmation before execution.

Add the following component to your frontend:

```tsx title="app/page.tsx" "use client";

import { useChat } from "@ai-sdk/react"; import { DefaultChatTransport, type ToolUIPart } from "ai"; import { useState } from "react"; import { CheckIcon, XIcon } from "lucide-react"; import { Button } from "@/components/ui/button"; import { Confirmation, ConfirmationRequest, ConfirmationAccepted, ConfirmationRejected, ConfirmationActions, ConfirmationAction, } from "@/components/ai-elements/confirmation"; import { MessageResponse } from "@/components/ai-elements/message";

type DeleteFileInput = { filePath: string; confirm: boolean; };

type DeleteFileToolUIPart = ToolUIPart<{ delete_file: { input: DeleteFileInput; output: { success: boolean; message: string }; }; }>;

const Example = () => { const { messages, sendMessage, status, addToolApprovalResponse } = useChat({ transport: new DefaultChatTransport({ api: "/api/chat", }), });

const handleDeleteFile = () => { sendMessage({ text: "Delete the file at /tmp/example.txt" }); };

const latestMessage = messages[messages.length - 1]; const deleteTool = latestMessage?.parts?.find( (part) => part.type === "tool-delete_file" ) as DeleteFileToolUIPart | undefined;

return ( <div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]"> <div className="flex flex-col h-full space-y-4"> <Button onClick={handleDeleteFile} disabled={status !== "ready"}> Delete Example File </Button>

{deleteTool?.approval && ( <Confirmation approval={deleteTool.approval} state={deleteTool.state}> <ConfirmationRequest> This tool wants to delete:{" "} <code>{deleteTool.input?.filePath}</code> <br /> Do you approve this action? </ConfirmationRequest> <ConfirmationAccepted> <CheckIcon className="size-4" /> <span>You approved this tool execution</span> </ConfirmationAccepted> <ConfirmationRejected> <XIcon className="size-4" /> <span>You rejected this tool execution</span> </ConfirmationRejected> <ConfirmationActions> <ConfirmationAction variant="outline" onClick={() => addToolApprovalResponse({ id: deleteTool.approval!.id, approved: false, }) } > Reject </ConfirmationAction> <ConfirmationAction variant="default" onClick={() => addToolApprovalResponse({ id: deleteTool.approval!.id, approved: true, }) } > Approve </ConfirmationAction> </ConfirmationActions> </Confirmation> )}

{deleteTool?.output && ( <MessageResponse> {deleteTool.output.success ? deleteTool.output.message : Error: ${deleteTool.output.message}} </MessageResponse> )} </div> </div> ); };

export default Example;

Add the following route to your backend:

import { streamText, UIMessage, convertToModelMessages } from "ai"; import { z } from "zod";

// Allow streaming responses up to 30 seconds export const maxDuration = 30;

export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json();

const result = streamText({ model: "openai/gpt-5.4", messages: await convertToModelMessages(messages), tools: { delete_file: { description: "Delete a file from the file system", parameters: z.object({ filePath: z.string().describe("The path to the file to delete"), confirm: z .boolean() .default(false) .describe("Confirmation that the user wants to delete the file"), }), requireApproval: true, // Enable approval workflow execute: async ({ filePath, confirm }) => { if (!confirm) { return { success: false, message: "Deletion not confirmed", }; }

// Simulate file deletion await new Promise((resolve) => setTimeout(resolve, 500));

return { success: true, message: Successfully deleted ${filePath}, }; }, }, }, });

return result.toUIMessageStreamResponse(); }

## Features

- Context-based state management for approval workflow
- Conditional rendering based on approval state
- Support for approval-requested, approval-responded, output-denied, and output-available states
- Built on shadcn/ui Alert and Button components
- TypeScript support with comprehensive type definitions
- Customizable styling with Tailwind CSS
- Keyboard navigation and accessibility support
- Theme-aware with automatic dark mode support

## Examples

### Approval Request State

Shows the approval request with action buttons when state is `approval-requested`.

See `scripts/confirmation-request.tsx` for this example.

### Approved State

Shows the accepted status when user approves and state is `approval-responded` or `output-available`.

See `scripts/confirmation-accepted.tsx` for this example.

### Rejected State

Shows the rejected status when user rejects and state is `output-denied`.

See `scripts/confirmation-rejected.tsx` for this example.

## Props

### `<Confirmation />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `approval` | `ToolUIPart[` | - | The approval object containing the approval ID and status. If not provided or undefined, the component will not render. |
| `state` | `ToolUIPart[` | - | The current state of the tool (input-streaming, input-available, approval-requested, approval-responded, output-denied, or output-available). Will not render for input-streaming or input-available states. |
| `className` | `string` | - | Additional CSS classes to apply to the Alert component. |
| `...props` | `React.ComponentProps<typeof Alert>` | - | Any other props are spread to the Alert component. |

### `<ConfirmationRequest />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | The content to display when approval is requested. Only renders when state is  |

### `<ConfirmationAccepted />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | The content to display when approval is accepted. Only renders when approval.approved is true and state is  |

### `<ConfirmationRejected />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | The content to display when approval is rejected. Only renders when approval.approved is false and state is  |

### `<ConfirmationActions />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes to apply to the actions container. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the div element. Only renders when state is  |

### `<ConfirmationAction />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof Button>` | - | Any other props are spread to the Button component. Styled with h-8 px-3 text-sm classes by default. |

Connection

A custom connection line component for React Flow-based canvases with animated bezier curve styling.

The Connection component provides a styled connection line for React Flow canvases. It renders an animated bezier curve with a circle indicator at the target end, using consistent theming through CSS variables.

Installation

npx ai-elements@latest add connection

Features

• Smooth bezier curve animation for connection lines
• Visual indicator circle at the target position
• Theme-aware styling using CSS variables
• Cubic bezier curve calculation for natural flow
• Lightweight implementation with minimal props
• Full TypeScript support with React Flow types
• Compatible with React Flow's connection system

Props

<Connection />

Context

A compound component system for displaying AI model context window usage, token consumption, and cost estimation.

The Context component provides a comprehensive view of AI model usage through a compound component system. It displays context window utilization, token consumption breakdown (input, output, reasoning, cache), and cost estimation in an interactive hover card interface.

See scripts/context.tsx for this example.

Installation

npx ai-elements@latest add context

Features

• Compound Component Architecture: Flexible composition of context display elements
• Visual Progress Indicator: Circular SVG progress ring showing context usage percentage
• Token Breakdown: Detailed view of input, output, reasoning, and cached tokens
• Cost Estimation: Real-time cost calculation using the tokenlens library
• Intelligent Formatting: Automatic token count formatting (K, M, B suffixes)
• Interactive Hover Card: Detailed information revealed on hover
• Context Provider Pattern: Clean data flow through React Context API
• TypeScript Support: Full type definitions for all components
• Accessible Design: Proper ARIA labels and semantic HTML
• Theme Integration: Uses currentColor for automatic theme adaptation

Props

<Context />

<ContextTrigger />

<ContextContent />

<ContextContentHeader />

<ContextContentBody />

<ContextContentFooter />

Usage Components

All usage components (ContextInputUsage, ContextOutputUsage, ContextReasoningUsage, ContextCacheUsage) share the same props:

Component Architecture

The Context component uses a compound component pattern with React Context for data sharing:

1. `<Context>` - Root provider component that holds all context data 2. `<ContextTrigger>` - Interactive trigger element (default: button with percentage) 3. `<ContextContent>` - Hover card content container 4. `<ContextContentHeader>` - Header section with progress visualization 5. `<ContextContentBody>` - Body section for usage breakdowns 6. `<ContextContentFooter>` - Footer section for total cost 7. Usage Components - Individual token usage displays (Input, Output, Reasoning, Cache)

Token Formatting

The component uses Intl.NumberFormat with compact notation for automatic formatting:

• Under 1,000: Shows exact count (e.g., "842")
• 1,000+: Shows with K suffix (e.g., "32K")
• 1,000,000+: Shows with M suffix (e.g., "1.5M")
• 1,000,000,000+: Shows with B suffix (e.g., "2.1B")

Cost Calculation

When a modelId is provided, the component automatically calculates costs using the tokenlens library:

• Input tokens: Cost based on model's input pricing
• Output tokens: Cost based on model's output pricing
• Reasoning tokens: Special pricing for reasoning-capable models
• Cached tokens: Reduced pricing for cached input tokens
• Total cost: Sum of all token type costs

Costs are formatted using Intl.NumberFormat with USD currency.

Styling

The component uses Tailwind CSS classes and follows your design system:

• Progress indicator uses currentColor for theme adaptation
• Hover card has customizable width and padding
• Footer has a secondary background for visual separation
• All text sizes use the text-xs class for consistency
• Muted foreground colors for secondary information

Controls

A styled controls component for React Flow-based canvases with zoom and fit view functionality.

The Controls component provides interactive zoom and fit view controls for React Flow canvases. It includes a modern, themed design with backdrop blur and card styling.

Installation

npx ai-elements@latest add controls

Features

• Zoom in/out controls
• Fit view button to center and scale content
• Rounded pill design with backdrop blur
• Theme-aware card background
• Subtle drop shadow for depth
• Full TypeScript support
• Compatible with all React Flow control features

Props

<Controls />

Conversation

Wraps messages and automatically scrolls to the bottom. Also includes a scroll button that appears when not at the bottom.

The Conversation component wraps messages and automatically scrolls to the bottom. Also includes a scroll button that appears when not at the bottom.

<Preview path="conversation" className="p-0" />

Installation

npx ai-elements@latest add conversation

Usage with AI SDK

Build a simple conversational UI with Conversation and `PromptInput`:

Add the following component to your frontend:

```tsx title="app/page.tsx" "use client";

import { Conversation, ConversationContent, ConversationDownload, ConversationEmptyState, ConversationScrollButton, } from "@/components/ai-elements/conversation"; import { Message, MessageContent, MessageResponse, } from "@/components/ai-elements/message"; import { Input, PromptInputTextarea, PromptInputSubmit, } from "@/components/ai-elements/prompt-input"; import { MessageSquare } from "lucide-react"; import { useState } from "react"; import { useChat } from "@ai-sdk/react";

const ConversationDemo = () => { const [input, setInput] = useState(""); const { messages, sendMessage, status } = useChat();

const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (input.trim()) { sendMessage({ text: input }); setInput(""); } };

return ( <div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]"> <div className="flex flex-col h-full"> <Conversation> <ConversationContent> {messages.length === 0 ? ( <ConversationEmptyState icon={<MessageSquare className="size-12" />} title="Start a conversation" description="Type a message below to begin chatting" /> ) : ( messages.map((message) => ( <Message from={message.role} key={message.id}> <MessageContent> {message.parts.map((part, i) => { switch (part.type) { case "text": // we don't use any reasoning or tool calls in this example return ( <MessageResponse key={${message.id}-${i}}> {part.text} </MessageResponse> ); default: return null; } })} </MessageContent> </Message> )) )} </ConversationContent> <ConversationDownload messages={messages} /> <ConversationScrollButton /> </Conversation>

<Input onSubmit={handleSubmit} className="mt-4 w-full max-w-2xl mx-auto relative" > <PromptInputTextarea value={input} placeholder="Say something..." onChange={(e) => setInput(e.currentTarget.value)} className="pr-12" /> <PromptInputSubmit status={status === "streaming" ? "streaming" : "ready"} disabled={!input.trim()} className="absolute bottom-1 right-1" /> </Input> </div> </div> ); };

export default ConversationDemo;

Add the following route to your backend:

import { streamText, UIMessage, convertToModelMessages } from "ai";

// Allow streaming responses up to 30 seconds export const maxDuration = 30;

export async function POST(req: Request) { const { messages }: { messages: UIMessage[] } = await req.json();

const result = streamText({ model: "openai/gpt-5.4", messages: await convertToModelMessages(messages), });

return result.toUIMessageStreamResponse(); }

## Features

- Automatic scrolling to the bottom when new messages are added
- Smooth scrolling behavior with configurable animation
- Scroll button that appears when not at the bottom
- Download conversation as Markdown
- Responsive design with customizable padding and spacing
- Flexible content layout with consistent message spacing
- Accessible with proper ARIA roles for screen readers
- Customizable styling through className prop
- Support for any number of child message components

## Props

### `<Conversation />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `contextRef` | `React.Ref<StickToBottomContext>` | - | Optional ref to access the StickToBottom context object. |
| `instance` | `StickToBottomInstance` | - | Optional instance for controlling the StickToBottom component. |
| `children` | `((context: StickToBottomContext) => ReactNode) | ReactNode` | - | Render prop or ReactNode for custom rendering with context. |
| `...props` | `Omit<React.HTMLAttributes<HTMLDivElement>, ` | - | Any other props are spread to the root div. |

### `<ConversationContent />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `((context: StickToBottomContext) => ReactNode) | ReactNode` | - | Render prop or ReactNode for custom rendering with context. |
| `...props` | `Omit<React.HTMLAttributes<HTMLDivElement>, ` | - | Any other props are spread to the root div. |

### `<ConversationEmptyState />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | - | The title text to display. |
| `description` | `string` | - | The description text to display. |
| `icon` | `React.ReactNode` | - | Optional icon to display above the text. |
| `children` | `React.ReactNode` | - | Optional additional content to render below the text. |
| `...props` | `ComponentProps<` | - | Any other props are spread to the root div. |

### `<ConversationScrollButton />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `ComponentProps<typeof Button>` | - | Any other props are spread to the underlying shadcn/ui Button component. |

### `<ConversationDownload />`

A button that downloads the conversation as a Markdown file.

import { ConversationDownload } from "@/components/ai-elements/conversation";

<Conversation> <ConversationContent> {messages.map(...)} </ConversationContent> <ConversationDownload messages={messages} /> <ConversationScrollButton /> </Conversation>

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `messages` | `ConversationMessage[]` | Required | Array of messages to include in the download. |
| `filename` | `string` | - | The filename for the downloaded file. |
| `formatMessage` | `(message: ConversationMessage, index: number) => string` | - | Custom function to format each message in the output. |
| `...props` | `Omit<ComponentProps<typeof Button>, ` | - | Any other props are spread to the underlying shadcn/ui Button component. |

### `messagesToMarkdown`

A utility function to convert messages to Markdown format. Useful for custom download implementations.

import { messagesToMarkdown } from "@/components/ai-elements/conversation";

const markdown = messagesToMarkdown(messages);

// With custom formatter const customMarkdown = messagesToMarkdown( messages, (msg, i) => [${msg.role}]: ${msg.content} );

Edge

Customizable edge components for React Flow canvases with animated and temporary states.

The Edge component provides two pre-styled edge types for React Flow canvases: Temporary for dashed temporary connections and Animated for connections with animated indicators.

Installation

npx ai-elements@latest add edge

Features

• Two distinct edge types: Temporary and Animated
• Temporary edges use dashed lines with ring color
• Animated edges include a moving circle indicator
• Automatic handle position calculation
• Smart offset calculation based on handle type and position
• Uses Bezier curves for smooth, natural-looking connections
• Fully compatible with React Flow's edge system
• Type-safe implementation with TypeScript

Edge Types

Edge.Temporary

A dashed edge style for temporary or preview connections. Uses a simple Bezier path with a dashed stroke pattern.

Edge.Animated

A solid edge with an animated circle that moves along the path. The animation repeats indefinitely with a 2-second duration, providing visual feedback for active connections.

Props

Both edge types accept standard React Flow EdgeProps:

Environment Variables

Display environment variables with masking and copy functionality.

The EnvironmentVariables component displays environment variables with value masking, visibility toggle, and copy functionality.

See scripts/environment-variables.tsx for this example.

Installation

npx ai-elements@latest add environment-variables

Features

• Value masking by default
• Toggle visibility switch
• Copy individual values
• Export format support (export KEY="value")
• Required badge indicator

Props

<EnvironmentVariables />

<EnvironmentVariablesHeader />

<EnvironmentVariablesTitle />

<EnvironmentVariablesToggle />

<EnvironmentVariablesContent />

<EnvironmentVariable />

<EnvironmentVariableGroup />

<EnvironmentVariableName />

<EnvironmentVariableValue />

<EnvironmentVariableCopyButton />

<EnvironmentVariableRequired />

File Tree

Display hierarchical file and folder structure with expand/collapse functionality.

The FileTree component displays a hierarchical file system structure with expandable folders and file selection.

See scripts/file-tree.tsx for this example.

Installation

npx ai-elements@latest add file-tree

Features

• Hierarchical folder structure
• Expand/collapse folders
• File selection with callback
• Keyboard accessible
• Customizable icons
• Controlled and uncontrolled modes

Examples

Basic Usage

See scripts/file-tree-basic.tsx for this example.

With Selection

See scripts/file-tree-selection.tsx for this example.

Default Expanded

See scripts/file-tree-expanded.tsx for this example.

Props

<FileTree />

<FileTreeFolder />

<FileTreeFile />

Subcomponents

• FileTreeIcon - Icon wrapper
• FileTreeName - Name text
• FileTreeActions - Action buttons container (stops click propagation)

Image

Displays AI-generated images from the AI SDK.

The Image component displays AI-generated images from the AI SDK. It accepts a `Experimental_GeneratedImage` object from the AI SDK's generateImage function and automatically renders it as an image.

See scripts/image.tsx for this example.

Installation

npx ai-elements@latest add image

Usage with AI SDK

Build a simple app allowing a user to generate an image given a prompt.

Install the @ai-sdk/openai package:

npm i @ai-sdk/openai

Add the following component to your frontend:

```tsx title="app/page.tsx" "use client";

import { Image } from "@/components/ai-elements/image"; import { Input, PromptInputTextarea, PromptInputSubmit, } from "@/components/ai-elements/prompt-input"; import { useState } from "react"; import { Spinner } from "@/components/ui/spinner";

const ImageDemo = () => { const [prompt, setPrompt] = useState("A futuristic cityscape at sunset"); const [imageData, setImageData] = useState<any>(null); const [isLoading, setIsLoading] = useState(false);

const handleSubmit = async (e: React.FormEvent) => { e.preventDefault(); if (!prompt.trim()) return; setPrompt("");

setIsLoading(true); try { const response = await fetch("/api/image", { method: "POST", body: JSON.stringify({ prompt: prompt.trim() }), });

const data = await response.json();

setImageData(data); } catch (error) { console.error("Error generating image:", error); } finally { setIsLoading(false); } };

return ( <div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]"> <div className="flex flex-col h-full"> <div className="flex-1 overflow-y-auto p-4"> {imageData && ( <div className="flex justify-center"> <Image {...imageData} alt="Generated image" className="h-[300px] aspect-square border rounded-lg" /> </div> )} {isLoading && <Spinner />} </div>

<Input onSubmit={handleSubmit} className="mt-4 w-full max-w-2xl mx-auto relative" > <PromptInputTextarea value={prompt} placeholder="Describe the image you want to generate..." onChange={(e) => setPrompt(e.currentTarget.value)} className="pr-12" /> <PromptInputSubmit status={isLoading ? "submitted" : "ready"} disabled={!prompt.trim()} className="absolute bottom-1 right-1" /> </Input> </div> </div> ); };

export default ImageDemo;

Add the following route to your backend:

import { openai } from "@ai-sdk/openai"; import { experimental_generateImage } from "ai";

export async function POST(req: Request) { const { prompt }: { prompt: string } = await req.json();

const { image } = await experimental_generateImage({ model: openai.image("dall-e-3"), prompt: prompt, size: "1024x1024", });

return Response.json({ base64: image.base64, uint8Array: image.uint8Array, mediaType: image.mediaType, }); }

## Features

- Accepts `Experimental_GeneratedImage` objects directly from the AI SDK
- Automatically creates proper data URLs from base64-encoded image data
- Supports all standard HTML image attributes
- Responsive by default with `max-w-full h-auto` styling
- Customizable with additional CSS classes
- Includes proper TypeScript types for AI SDK compatibility

## Props

### `<Image />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `alt` | `string` | - | Alternative text for the image. |
| `className` | `string` | - | Additional CSS classes to apply to the image. |
| `...props` | `Experimental_GeneratedImage` | - | The image data to display, as returned by the AI SDK. |

Inline Citation

A hoverable citation component that displays source information and quotes inline with text, perfect for AI-generated content with references.

The InlineCitation component provides a way to display citations inline with text content, similar to academic papers or research documents. It consists of a citation pill that shows detailed source information on hover, making it perfect for AI-generated content that needs to reference sources.

See scripts/inline-citation.tsx for this example.

Installation

npx ai-elements@latest add inline-citation

Usage with AI SDK

Build citations for AI-generated content using `experimental_generateObject`.

Add the following component to your frontend:

```tsx title="app/page.tsx" "use client";

import { experimental_useObject as useObject } from "@ai-sdk/react"; import { InlineCitation, InlineCitationText, InlineCitationCard, InlineCitationCardTrigger, InlineCitationCardBody, InlineCitationCarousel, InlineCitationCarouselContent, InlineCitationCarouselItem, InlineCitationCarouselHeader, InlineCitationCarouselIndex, InlineCitationCarouselPrev, InlineCitationCarouselNext, InlineCitationSource, InlineCitationQuote, } from "@/components/ai-elements/inline-citation"; import { Button } from "@/components/ui/button"; import { citationSchema } from "@/app/api/citation/route";

const CitationDemo = () => { const { object, submit, isLoading } = useObject({ api: "/api/citation", schema: citationSchema, });

const handleSubmit = (topic: string) => { submit({ prompt: topic }); };

return ( <div className="max-w-4xl mx-auto p-6 space-y-6"> <div className="flex gap-2 mb-6"> <Button onClick={() => handleSubmit("artificial intelligence")} disabled={isLoading} variant="outline" > Generate AI Content </Button> <Button onClick={() => handleSubmit("climate change")} disabled={isLoading} variant="outline" > Generate Climate Content </Button> </div>

{isLoading && !object && ( <div className="text-muted-foreground"> Generating content with citations... </div> )}

{object?.content && ( <div className="prose prose-sm max-w-none"> <p className="leading-relaxed"> {object.content.split(/(\[\d+\])/).map((part, index) => { const citationMatch = part.match(/\[(\d+)\]/); if (citationMatch) { const citationNumber = citationMatch[1]; const citation = object.citations?.find( (c: any) => c.number === citationNumber );

if (citation) { return ( <InlineCitation key={index}> <InlineCitationCard> <InlineCitationCardTrigger sources={[citation.url]} /> <InlineCitationCardBody> <InlineCitationCarousel> <InlineCitationCarouselHeader> <InlineCitationCarouselPrev /> <InlineCitationCarouselNext /> <InlineCitationCarouselIndex /> </InlineCitationCarouselHeader> <InlineCitationCarouselContent> <InlineCitationCarouselItem> <InlineCitationSource title={citation.title} url={citation.url} description={citation.description} /> {citation.quote && ( <InlineCitationQuote> {citation.quote} </InlineCitationQuote> )} </InlineCitationCarouselItem> </InlineCitationCarouselContent> </InlineCitationCarousel> </InlineCitationCardBody> </InlineCitationCard> </InlineCitation> ); } } return part; })} </p> </div> )} </div> ); };

export default CitationDemo;

Add the following route to your backend:

import { streamObject } from "ai"; import { z } from "zod";

export const citationSchema = z.object({ content: z.string(), citations: z.array( z.object({ number: z.string(), title: z.string(), url: z.string(), description: z.string().optional(), quote: z.string().optional(), }) ), });

// Allow streaming responses up to 30 seconds export const maxDuration = 30;

export async function POST(req: Request) { const { prompt } = await req.json();

const result = streamObject({ model: "openai/gpt-5.4", schema: citationSchema, prompt: `Generate a well-researched paragraph about ${prompt} with proper citations.

Include:

• A comprehensive paragraph with inline citations marked as [1], [2], etc.
• 2-3 citations with realistic source information
• Each citation should have a title, URL, and optional description/quote
• Make the content informative and the sources credible

Format citations as numbered references within the text.`, });

return result.toTextStreamResponse(); }

## Features

- Hover interaction to reveal detailed citation information
- **Carousel navigation** for multiple citations with prev/next controls
- **Live index tracking** showing current slide position (e.g., "1/5")
- Support for source titles, URLs, and descriptions
- Optional quote blocks for relevant excerpts
- Composable architecture for flexible citation formats
- Accessible design with proper keyboard navigation
- Seamless integration with AI-generated content
- Clean visual design that doesn't disrupt reading flow
- Smart badge display showing source hostname and count

## Usage with AI SDK

Currently, there is no official support for inline citations with Streamdown or the Response component. This is because:

- There isn't any good markdown syntax for inline citations
- Language models don't naturally respond with inline citation syntax
- The AI SDK doesn't have built-in support for inline citations

### Potential Approaches

While these methods are hypothetical and not officially supported, there are two conceptual ways inline citations could work with Streamdown:

1. **Footnote conversion**: GitHub Flavored Markdown (GFM) handles footnotes using `[^1]` syntax. You could hypothetically remove the default footnote rendering and convert footnotes to inline citations instead.

2. **Custom HTML syntax**: You could add a system prompt instructing the model to use a special HTML syntax like `<citation />` and pass that as a custom component to Streamdown.

These approaches require custom implementation and are not currently supported out of the box. We will investigate official support for this use case in the future.

For now, the recommended approach is to use `experimental_useObject` (as shown in the usage example above) to generate structured citation data, then manually parse and render inline citations.

## Props

### `<InlineCitation />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the root span element. |

### `<InlineCitationText />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying span element. |

### `<InlineCitationCard />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the HoverCard component. |

### `<InlineCitationCardTrigger />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `sources` | `string[]` | - | Array of source URLs. The length determines the number displayed in the badge. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying button element. |

### `<InlineCitationCardBody />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |

### `<InlineCitationCarousel />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof Carousel>` | - | Any other props are spread to the underlying Carousel component. |

### `<InlineCitationCarouselContent />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying CarouselContent component. |

### `<InlineCitationCarouselItem />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |

### `<InlineCitationCarouselHeader />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |

### `<InlineCitationCarouselIndex />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. Children will override the default index display. |

### `<InlineCitationCarouselPrev />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof CarouselPrevious>` | - | Any other props are spread to the underlying CarouselPrevious component. |

### `<InlineCitationCarouselNext />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof CarouselNext>` | - | Any other props are spread to the underlying CarouselNext component. |

### `<InlineCitationSource />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | - | The title of the source. |
| `url` | `string` | - | The URL of the source. |
| `description` | `string` | - | A brief description of the source. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div. |

### `<InlineCitationQuote />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying blockquote element. |

AI SDK Integration

How to integrate AI Elements with Vercel AI SDK.

useChat Hook

The core hook for chat functionality.

'use client';
import { useChat } from '@ai-sdk/react';

export function Chat() {
  const {
    messages,      // UIMessage[] - message history
    sendMessage,   // Send new message
    status,        // ChatStatus: 'ready' | 'submitted' | 'streaming' | 'error'
    regenerate,    // Regenerate last assistant message
    error,         // Error object if status === 'error'
  } = useChat();

  // ...
}

ChatStatus Values

UIMessage Structure

Messages have role and parts array:

type UIMessage = {
  id: string;
  role: 'user' | 'assistant';
  parts: UIMessagePart[];
};

type UIMessagePart =
  | { type: 'text'; text: string }
  | { type: 'reasoning'; text: string }
  | { type: 'source-url'; url: string; title?: string }
  | { type: 'tool-invocation'; toolName: string; input: unknown; state: ToolState }
  | { type: 'tool-result'; toolName: string; output: unknown; errorText?: string }
  | { type: 'file'; url: string; mediaType: string; filename?: string };

Message Parts Rendering

Switch on part.type to render appropriate components:

{messages.map((message) => (
  <div key={message.id}>
    {message.parts.map((part, i) => {
      switch (part.type) {
        case 'text':
          return (
            <Message key={i} from={message.role}>
              <MessageContent>
                <MessageResponse>{part.text}</MessageResponse>
              </MessageContent>
            </Message>
          );

        case 'reasoning':
          return (
            <Reasoning
              key={i}
              isStreaming={status === 'streaming' && isLastPart(message, i)}
            >
              <ReasoningTrigger />
              <ReasoningContent>{part.text}</ReasoningContent>
            </Reasoning>
          );

        case 'source-url':
          return (
            <Source key={i} href={part.url} title={part.title} />
          );

        default:
          // Handle tool-* types
          if (part.type.startsWith('tool-')) {
            return (
              <Tool key={i}>
                <ToolHeader type={part.type} state={part.state} title={part.toolName} />
                <ToolContent>
                  <ToolInput input={part.input} />
                  <ToolOutput output={part.output} errorText={part.errorText} />
                </ToolContent>
              </Tool>
            );
          }
          return null;
      }
    })}
  </div>
))}

API Route Pattern

Basic Route

// app/api/chat/route.ts
import { streamText, UIMessage, convertToModelMessages } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();

  const result = streamText({
    model: anthropic('claude-sonnet-4-6'),
    messages: convertToModelMessages(messages),
    system: 'You are a helpful assistant.',
  });

  return result.toUIMessageStreamResponse({
    sendSources: true,
    sendReasoning: true,
  });
}

With Dynamic Model Selection

export async function POST(req: Request) {
  const {
    messages,
    model,
    webSearch,
  }: {
    messages: UIMessage[];
    model: string;
    webSearch: boolean;
  } = await req.json();

  const result = streamText({
    // Use different model for web search
    model: webSearch ? 'perplexity/sonar' : model,
    messages: convertToModelMessages(messages),
    system: 'You are a helpful assistant.',
  });

  return result.toUIMessageStreamResponse({
    sendSources: true,
    sendReasoning: true,
  });
}

toUIMessageStreamResponse Options

Sending Messages with Options

const { sendMessage } = useChat();

// Basic text message
sendMessage({ text: 'Hello!' });

// With file attachments
sendMessage({
  text: 'What is in this image?',
  files: [{ type: 'file', url: dataUrl, mediaType: 'image/png' }],
});

// With custom body options
sendMessage(
  { text: 'Search the web for this' },
  {
    body: {
      model: 'perplexity/sonar',
      webSearch: true,
    },
  }
);

File Attachment Flow

Client-side (PromptInput)

const handleSubmit = async (message: PromptInputMessage) => {
  // message.files are FileUIPart[] with blob URLs
  // PromptInput automatically converts blob URLs to data URLs

  sendMessage({
    text: message.text,
    files: message.files, // Already converted to data URLs
  });
};

Server-side Processing

// Files are in message parts
const messages = convertToModelMessages(uiMessages);
// Files are automatically handled by AI SDK

Error Handling

const { error, status } = useChat();

{status === 'error' && (
  <Alert variant="destructive">
    <AlertDescription>
      {error?.message || 'An error occurred'}
    </AlertDescription>
  </Alert>
)}

Regenerate Last Response

const { regenerate } = useChat();

<MessageAction
  label="Retry"
  onClick={() => regenerate()}
>
  <RefreshCcwIcon className="size-3" />
</MessageAction>

MCP Server Setup

AI Elements provides an MCP server for component documentation.

Claude Code

claude mcp add --transport http ai-elements https://registry.ai-sdk.dev/api/mcp

Cursor / Other Tools

// .cursor/mcp.json or equivalent
{
  "mcpServers": {
    "ai-elements": {
      "command": "bunx",
      "args": ["--bun", "mcp-remote", "https://registry.ai-sdk.dev/api/mcp"]
    }
  }
}

Usage

After setup, ask your AI assistant:

• "What AI Elements components are available?"
• "Show me how to use PromptInput with file attachments"
• "Help me create an AI chat layout"

Provider Setup

AI Gateway (Recommended)

# .env.local
AI_GATEWAY_API_KEY=your_key_here

AI Gateway provides:

• $5/month free usage
• Unified API key for multiple providers
• Get key at: https://ai-gateway.dev

Direct Provider Setup

# .env.local
ANTHROPIC_API_KEY=your_key
OPENAI_API_KEY=your_key

Dependencies

bun add ai @ai-sdk/react @ai-sdk/anthropic zod

JSX Preview

A component that dynamically renders JSX strings with streaming support for AI-generated UI.

The JSXPreview component renders JSX strings dynamically, supporting streaming scenarios where JSX may be incomplete. It automatically closes unclosed tags during streaming, making it ideal for displaying AI-generated UI components in real-time.

See scripts/jsx-preview.tsx for this example.

Installation

npx ai-elements@latest add jsx-preview

Features

• Renders JSX strings dynamically using react-jsx-parser
• Streaming support with automatic tag completion
• Custom component injection for rendering your own components
• Error handling with customizable error display
• Context-based architecture for flexible composition

Usage with AI SDK

The JSXPreview component integrates with the AI SDK to render generated UI in real-time:

```tsx title="components/generated-ui.tsx" "use client";

import { JSXPreview, JSXPreviewContent, JSXPreviewError, } from "@/components/ai-elements/jsx-preview";

type GeneratedUIProps = { jsx: string; isStreaming: boolean; };

export const GeneratedUI = ({ jsx, isStreaming }: GeneratedUIProps) => ( <JSXPreview jsx={jsx} isStreaming={isStreaming} onError={(error) => console.error("JSX Parse Error:", error)} > <JSXPreviewContent /> <JSXPreviewError /> </JSXPreview> );

### With Custom Components

You can inject custom components to be used within the rendered JSX:

"use client";

import { JSXPreview, JSXPreviewContent, } from "@/components/ai-elements/jsx-preview"; import { Button } from "@/components/ui/button"; import { Card } from "@/components/ui/card";

const customComponents = { Button, Card, };

export const GeneratedUIWithComponents = ({ jsx }: { jsx: string }) => ( <JSXPreview jsx={jsx} components={customComponents}> <JSXPreviewContent /> </JSXPreview> );

## Props

### `<JSXPreview />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `jsx` | `string` | Required | The JSX string to render. |
| `isStreaming` | `boolean` | `false` | When true, automatically completes unclosed tags. |
| `components` | `Record<string, React.ComponentType>` | - | Custom components available within the rendered JSX. |
| `bindings` | `Record<string, unknown>` | - | Variables and functions available within the JSX scope. |
| `onError` | `(error: Error) => void` | - | Callback fired when a parsing or rendering error occurs. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div element. |

### `<JSXPreviewContent />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `renderError` | `JsxParserProps[` | - | Custom error renderer passed to react-jsx-parser. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div element. |

### `<JSXPreviewError />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode | ((error: Error) => ReactNode)` | - | Custom error content or render function receiving the error. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the underlying div element. |

Loader

A spinning SVG loader icon for indicating loading states in AI chat interfaces.

Installation

bunx --bun ai-elements@latest add loader

Usage

import { Loader } from '@/components/ai-elements/loader';

// Show while waiting for AI response
{status === 'submitted' && <Loader />}

// Custom size
<Loader size={12} />

// With label
<div className="flex items-center gap-2 text-xs text-muted-foreground">
  <Loader size={12} />
  <span>Loading suggestions…</span>
</div>

Props

<Loader />

Message

A comprehensive suite of components for displaying chat messages, including message rendering, branching, actions, and markdown responses.

The Message component suite provides a complete set of tools for building chat interfaces. It includes components for displaying messages from users and AI assistants, managing multiple response branches, adding action buttons, and rendering markdown content.

See scripts/message.tsx for this example.

Installation

npx ai-elements@latest add message

Features

• Displays messages from both user and AI assistant with distinct styling and automatic alignment
• Minimalist flat design with user messages in secondary background and assistant messages full-width
• Response branching with navigation controls to switch between multiple AI response versions
• Markdown rendering with GFM support (tables, task lists, strikethrough), math equations, and smart streaming
• Action buttons for common operations (retry, like, dislike, copy, share) with tooltips and state management
• File attachments display with support for images and generic files with preview and remove functionality
• Code blocks with syntax highlighting and copy-to-clipboard functionality
• Keyboard accessible with proper ARIA labels
• Responsive design that adapts to different screen sizes
• Seamless light/dark theme integration

Usage with AI SDK

Build a simple chat UI where the user can copy or regenerate the most recent message.

Add the following component to your frontend:

```tsx title="app/page.tsx" "use client";

import { useState } from "react"; import { MessageActions, MessageAction, } from "@/components/ai-elements/message"; import { Message, MessageContent } from "@/components/ai-elements/message"; import { Conversation, ConversationContent, ConversationScrollButton, } from "@/components/ai-elements/conversation"; import { PromptInput, PromptInputTextarea, PromptInputSubmit, } from "@/components/ai-elements/prompt-input"; import { MessageResponse } from "@/components/ai-elements/message"; import { RefreshCcwIcon, CopyIcon } from "lucide-react"; import { useChat } from "@ai-sdk/react"; import { Fragment } from "react";

const ActionsDemo = () => { const [input, setInput] = useState(""); const { messages, sendMessage, status, regenerate } = useChat();

const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (input.trim()) { sendMessage({ text: input }); setInput(""); } };

return ( <div className="max-w-4xl mx-auto p-6 relative size-full rounded-lg border h-[600px]"> <div className="flex flex-col h-full"> <Conversation> <ConversationContent> {messages.map((message, messageIndex) => ( <Fragment key={message.id}> {message.parts.map((part, i) => { switch (part.type) { case "text": const isLastMessage = messageIndex === messages.length - 1;

return ( <Fragment key={${message.id}-${i}}> <Message from={message.role}> <MessageContent> <MessageResponse>{part.text}</MessageResponse> </MessageContent> </Message> {message.role === "assistant" && isLastMessage && ( <MessageActions> <MessageAction onClick={() => regenerate()} label="Retry" > <RefreshCcwIcon className="size-3" /> </MessageAction> <MessageAction onClick={() => navigator.clipboard.writeText(part.text) } label="Copy" > <CopyIcon className="size-3" /> </MessageAction> </MessageActions> )} </Fragment> ); default: return null; } })} </Fragment> ))} </ConversationContent> <ConversationScrollButton /> </Conversation>

<PromptInput onSubmit={handleSubmit} className="mt-4 w-full max-w-2xl mx-auto relative" > <PromptInputTextarea value={input} placeholder="Say something..." onChange={(e) => setInput(e.currentTarget.value)} className="pr-12" /> <PromptInputSubmit status={status === "streaming" ? "streaming" : "ready"} disabled={!input.trim()} className="absolute bottom-1 right-1" /> </PromptInput> </div> </div> ); };

export default ActionsDemo;

## Props

### `<Message />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `from` | `UIMessage[` | - | The role of the message sender ( |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the root div. |

### `<MessageContent />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the content div. |

### `<MessageResponse />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `string` | - | The markdown content to render. |
| `parseIncompleteMarkdown` | `boolean` | `true` | Whether to parse and fix incomplete markdown syntax (e.g., unclosed code blocks or lists). |
| `className` | `string` | - | CSS class names to apply to the wrapper div element. |
| `components` | `object` | - | Custom React components to use for rendering markdown elements (e.g., custom heading, paragraph, code block components). |
| `allowedImagePrefixes` | `string[]` | `[` | Array of allowed URL prefixes for images. Use [ |
| `allowedLinkPrefixes` | `string[]` | `[` | Array of allowed URL prefixes for links. Use [ |
| `defaultOrigin` | `string` | - | Default origin to use for relative URLs in links and images. |
| `rehypePlugins` | `array` | `[rehypeKatex]` | Array of rehype plugins to use for processing HTML. Includes KaTeX for math rendering by default. |
| `remarkPlugins` | `array` | `[remarkGfm, remarkMath]` | Array of remark plugins to use for processing markdown. Includes GitHub Flavored Markdown and math support by default. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the root div. |

### `<MessageActions />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | HTML attributes to spread to the root div. |

### `<MessageAction />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `tooltip` | `string` | - | Optional tooltip text shown on hover. |
| `label` | `string` | - | Accessible label for screen readers. Also used as fallback if tooltip is not provided. |
| `...props` | `React.ComponentProps<typeof Button>` | - | Any other props are spread to the underlying shadcn/ui Button component. |

### `<MessageBranch />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultBranch` | `number` | `0` | The index of the branch to show by default. |
| `onBranchChange` | `(branchIndex: number) => void` | - | Callback fired when the branch changes. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the root div. |

### `<MessageBranchContent />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the root div. |

### `<MessageBranchSelector />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `from` | `UIMessage[` | - | Aligns the selector for user, assistant or system messages. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the selector container. |

### `<MessageBranchPrevious />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof Button>` | - | Any other props are spread to the underlying shadcn/ui Button component. |

### `<MessageBranchNext />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.ComponentProps<typeof Button>` | - | Any other props are spread to the underlying shadcn/ui Button component. |

### `<MessageBranchPage />`

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `...props` | `React.HTMLAttributes<HTMLSpanElement>` | - | Any other props are spread to the underlying span element. |

### `<MessageAttachments />`

A container component for displaying file attachments in a message. Automatically positions attachments at the end of the message with proper spacing and alignment.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `ReactNode` | - | MessageAttachment components to render. Returns null if no children provided. |
| `...props` | `React.ComponentProps<` | - | Any other props are spread to the root div. |

**Example:**

<MessageAttachments className="mb-2"> {files.map((attachment) => ( <MessageAttachment data={attachment} key={attachment.url} /> ))} </MessageAttachments>

### `<MessageAttachment />`

Displays a single file attachment. Images are shown as thumbnails (96px × 96px) with rounded corners. Non-image files show a paperclip icon with the filename.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `data` | `FileUIPart` | - | The file data to display. Must include url and mediaType. |
| `onRemove` | `() => void` | - | Optional callback fired when the remove button is clicked. If provided, a remove button will appear on hover. |
| `...props` | `React.HTMLAttributes<HTMLDivElement>` | - | Any other props are spread to the root div. |

**Example:**

<MessageAttachment data={{ type: "file", url: "https://example.com/image.jpg", mediaType: "image/jpeg", filename: "image.jpg", }} onRemove={() => console.log("Remove clicked")} />

Model Selector

A searchable command palette for selecting AI models in your chat interface.

The ModelSelector component provides a searchable command palette interface for selecting AI models. It's built on top of the cmdk library and provides a keyboard-navigable interface with search functionality.

See scripts/model-selector.tsx for this example.

Installation

npx ai-elements@latest add model-selector

Features

• Searchable interface with keyboard navigation
• Fuzzy search filtering across model names
• Grouped model organization by provider
• Keyboard shortcuts support
• Empty state handling
• Customizable styling with Tailwind CSS
• Built on cmdk for excellent accessibility
• TypeScript support with proper type definitions

Props

<ModelSelector />

<ModelSelectorTrigger />

<ModelSelectorContent />

<ModelSelectorDialog />

<ModelSelectorInput />

<ModelSelectorList />

<ModelSelectorEmpty />

<ModelSelectorGroup />

<ModelSelectorItem />

<ModelSelectorShortcut />

<ModelSelectorSeparator />

<ModelSelectorLogo />

<ModelSelectorLogoGroup />

<ModelSelectorName />

Panel

A styled panel component for React Flow-based canvases to position custom UI elements.

The Panel component provides a positioned container for custom UI elements on React Flow canvases. It includes modern card styling with backdrop blur and flexible positioning options.

Installation

npx ai-elements@latest add panel

Features

• Flexible positioning (top-left, top-right, bottom-left, bottom-right, top-center, bottom-center)
• Rounded pill design with backdrop blur
• Theme-aware card background
• Flexbox layout for easy content alignment
• Subtle drop shadow for depth
• Full TypeScript support
• Compatible with React Flow's panel system

Props

<Panel />

Toolbar

A styled toolbar component for React Flow nodes with flexible positioning and custom actions.

The Toolbar component provides a positioned toolbar that attaches to nodes in React Flow canvases. It features modern card styling with backdrop blur and flexbox layout for action buttons and controls.

Installation

npx ai-elements@latest add toolbar

Features

• Attaches to any React Flow node
• Bottom positioning by default
• Rounded card design with border
• Theme-aware background styling
• Flexbox layout with gap spacing
• Full TypeScript support
• Compatible with all React Flow NodeToolbar features

Props

<Toolbar />