undefined

**Why this matters:**
- AI Elements is built ON TOP of shadcn/ui (won't work without it)
- Requires Next.js App Router (Pages Router not supported)
- AI SDK v5 has breaking changes from v4

**Missing prerequisites?** Use the `tailwind-v4-shadcn` skill first, then install AI SDK:
```bash
pnpm add ai@latest

undefined

**CRITICAL:**
- Components are copied into `components/ui/ai/` (NOT installed as npm package)
- Full source code ownership (modify as needed)
- Registry URL must be correct in `components.json`

// app/chat/page.tsx
'use client';

import { useChat } from 'ai/react';
import { Conversation } from '@/components/ui/ai/conversation';
import { Message } from '@/components/ui/ai/message';
import { MessageContent } from '@/components/ui/ai/message-content';
import { Response } from '@/components/ui/ai/response';
import { PromptInput } from '@/components/ui/ai/prompt-input';

export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat({
    api: '/api/chat'
  });

  return (
    <div className="flex h-screen flex-col">
      <Conversation className="flex-1">
        {messages.map((msg) => (
          <Message key={msg.id} role={msg.role}>
            <MessageContent>
              <Response markdown={msg.content} />
            </MessageContent>
          </Message>
        ))}
      </Conversation>

      <PromptInput
        value={input}
        onChange={handleInputChange}
        onSubmit={handleSubmit}
        disabled={isLoading}
      />
    </div>
  );
}

pnpm dlx ai-elements@latest init

undefined

**Component Purpose:**
- `message`: Container for single message (user/AI)
- `message-content`: Wrapper for message parts
- `conversation`: Auto-scrolling chat container
- `response`: Markdown renderer (streaming-optimized)
- `prompt-input`: Auto-resizing textarea with toolbar
- `actions`: Copy/regenerate/edit buttons
- `suggestion`: Quick prompt pills

undefined

**When to add each:**
- `tool`: Building AI assistants with function calling
- `reasoning`: Showing AI's thinking process (like Claude or o1)
- `sources`: Adding citations and references (like Perplexity)
- `code-block`: Chat includes code snippets
- `branch`: Multi-turn conversations with variations
- `task`: AI generates task lists with file references
- `image`: AI generates images (DALL-E, Stable Diffusion)
- `web-preview`: AI generates HTML/websites (Claude artifacts)
- `loader`: Show loading states during streaming

import { openai } from '@ai-sdk/openai';
import { streamText } from 'ai';

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

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
  });

  return result.toDataStreamResponse();
}

undefined

**Verification Checklist:**
- [ ] All components in `components/ui/ai/`
- [ ] `components.json` has AI Elements registry
- [ ] No TypeScript errors
- [ ] Chat interface renders
- [ ] Streaming works (type message → get response)
- [ ] Auto-scroll works during streaming

---

// Conditionally show voice button
const isSpeechSupported = typeof window !== 'undefined' &&
  ('webkitSpeechRecognition' in window || 'SpeechRecognition' in window);

<PromptInput
  enableSpeech={isSpeechSupported}
  // Fallback: Implement server-side STT (Whisper, Google Speech)
/>

<PromptInput
  className="min-h-[100px] sm:min-h-[60px]"  // Add responsive classes
  // ... other props
/>

// Merge reasoning chunks client-side
const processedMessages = messages.map(msg => {
  if (msg.annotations?.reasoning) {
    // Combine all reasoning into single string
    const merged = Array.isArray(msg.annotations.reasoning)
      ? msg.annotations.reasoning.join('\n\n')
      : msg.annotations.reasoning;
    return { ...msg, annotations: { ...msg.annotations, reasoning: merged } };
  }
  return msg;
});

undefined

undefined

// ✅ v5 (correct)
const { messages } = useChat();  // Direct messages array
msg.toolInvocations  // Tool calls here

// ❌ v4 (incorrect)
const { data } = useChat();  // Wrapped in data object
msg.tool_calls  // Different property name

// Memoize callbacks to prevent re-renders
import { useCallback } from 'react';

const { messages } = useChat({
  api: '/api/chat',
  onFinish: useCallback((message) => {
    console.log('Finished', message);
  }, [])  // Stable dependency array
});

// Pass raw markdown content, not rendered HTML
<Actions>
  <Actions.Copy content={msg.content} format="markdown" />
</Actions>

undefined

---

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/index.css",
    "baseColor": "zinc",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "shadcn": "https://ui.shadcn.com/registry",
    "ai-elements": "https://www.shadcn.io/ai/registry"
  }
}

'use client';

import { useChat } from 'ai/react';
import { Conversation, Message, MessageContent, Response, Actions } from '@/components/ui/ai';
import { PromptInput } from '@/components/ui/ai/prompt-input';

export default function ChatWithActions() {
  const { messages, input, handleInputChange, handleSubmit, reload, stop } = useChat();

  return (
    <div className="flex h-screen flex-col">
      <Conversation className="flex-1">
        {messages.map((msg) => (
          <Message key={msg.id} role={msg.role}>
            <MessageContent>
              <Response markdown={msg.content} />
              {msg.role === 'assistant' && (
                <Actions>
                  <Actions.Copy content={msg.content} />
                  <Actions.Regenerate onClick={() => reload()} />
                </Actions>
              )}
            </MessageContent>
          </Message>
        ))}
      </Conversation>

      <PromptInput
        value={input}
        onChange={handleInputChange}
        onSubmit={handleSubmit}
      />
    </div>
  );
}

'use client';

import { useChat } from 'ai/react';
import { Tool } from '@/components/ui/ai/tool';
import { z } from 'zod';

export default function ChatWithTools() {
  const { messages } = useChat({
    api: '/api/chat',
    async onToolCall({ toolCall }) {
      if (toolCall.toolName === 'get_weather') {
        // Execute tool
        return { temperature: 72, conditions: 'Sunny' };
      }
    }
  });

  return (
    <Conversation>
      {messages.map((msg) => (
        <Message key={msg.id} role={msg.role}>
          <MessageContent>
            {msg.content && <Response markdown={msg.content} />}

            {/* Render tool invocations */}
            {msg.toolInvocations?.map((tool) => (
              <Tool
                key={tool.toolCallId}
                name={tool.toolName}
                args={tool.args}
                result={tool.result}
                status={tool.state}  // "pending" | "success" | "error"
              />
            ))}
          </MessageContent>
        </Message>
      ))}
    </Conversation>
  );
}

'use client';

import { useChat } from 'ai/react';
import { Reasoning } from '@/components/ui/ai/reasoning';

export default function ChatWithReasoning() {
  const { messages, isLoading } = useChat({
    api: '/api/chat',
    streamProtocol: 'text'
  });

  return (
    <Conversation>
      {messages.map((msg, idx) => {
        const reasoning = msg.annotations?.reasoning;
        const isStreaming = isLoading && idx === messages.length - 1;

        return (
          <Message key={msg.id} role={msg.role}>
            <MessageContent>
              {reasoning && (
                <Reasoning
                  content={reasoning}
                  streaming={isStreaming}
                  collapsed={!isStreaming}  // Collapse after done
                />
              )}
              <Response markdown={msg.content} />
            </MessageContent>
          </Message>
        );
      })}
    </Conversation>
  );
}

'use client';

import { useChat } from 'ai/react';
import { Sources, InlineCitation } from '@/components/ui/ai';

export default function ChatWithSources() {
  const { messages } = useChat({
    api: '/api/chat'
  });

  return (
    <Conversation>
      {messages.map((msg) => {
        const sources = msg.annotations?.sources || [];

        return (
          <Message key={msg.id} role={msg.role}>
            <MessageContent>
              <Response markdown={msg.content} />

              {/* Show sources at bottom */}
              {sources.length > 0 && (
                <Sources
                  sources={sources}
                  citations={msg.annotations?.citations || []}
                />
              )}
            </MessageContent>
          </Message>
        );
      })}
    </Conversation>
  );
}

'use client';

import { useChat } from 'ai/react';
import { CodeBlock } from '@/components/ui/ai/code-block';
import { Response } from '@/components/ui/ai/response';

export default function ChatWithCode() {
  const { messages } = useChat();

  return (
    <Conversation>
      {messages.map((msg) => (
        <Message key={msg.id} role={msg.role}>
          <MessageContent>
            {/* Response component auto-renders code blocks */}
            <Response
              markdown={msg.content}
              components={{
                // Optionally override code rendering
                code: ({ language, code }) => (
                  <CodeBlock
                    language={language}
                    code={code}
                    showLineNumbers={true}
                  />
                )
              }}
            />
          </MessageContent>
        </Message>
      ))}
    </Conversation>
  );
}

#!/bin/bash

**Example Usage:**
```bash
chmod +x scripts/setup-ai-elements.sh
./scripts/setup-ai-elements.sh

import { useVirtualizer } from '@tanstack/react-virtual';
import { useRef } from 'react';

function VirtualizedChat({ messages }) {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: messages.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 150,  // Average message height
    overscan: 5  // Render 5 extra items for smooth scrolling
  });

  return (
    <div ref={parentRef} className="h-screen overflow-y-auto">
      <div style={{ height: `${virtualizer.getTotalSize()}px`, position: 'relative' }}>
        {virtualizer.getVirtualItems().map((virtualRow) => (
          <div
            key={virtualRow.index}
            style={{
              position: 'absolute',
              top: 0,
              left: 0,
              width: '100%',
              height: `${virtualRow.size}px`,
              transform: `translateY(${virtualRow.start}px)`
            }}
          >
            <Message {...messages[virtualRow.index]} />
          </div>
        ))}
      </div>
    </div>
  );
}

/* src/index.css - Customize AI message colors */

:root {
  /* AI message background */
  --ai-message: hsl(var(--muted));
  --ai-message-foreground: hsl(var(--muted-foreground));

  /* User message background */
  --user-message: hsl(var(--primary));
  --user-message-foreground: hsl(var(--primary-foreground));

  /* Tool call colors */
  --tool-success: hsl(142 76% 36%);
  --tool-error: hsl(var(--destructive));
  --tool-pending: hsl(47 91% 58%);
}

.dark {
  --ai-message: hsl(var(--muted));
  --ai-message-foreground: hsl(var(--muted-foreground));
  /* ... dark mode variants */
}

// Add ARIA labels to interactive elements
<PromptInput
  aria-label="Chat message input"
  aria-describedby="chat-instructions"
/>

<Actions>
  <Actions.Copy
    aria-label="Copy message to clipboard"
    aria-live="polite"  // Announce copy success
  />
  <Actions.Regenerate
    aria-label="Regenerate AI response"
  />
</Actions>

// Screen reader announcements for streaming
<Response
  markdown={content}
  aria-live="polite"  // Announce updates during streaming
  aria-atomic="false"  // Only announce changes, not entire content
/>

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText, tool } from 'ai';
import { z } from 'zod';

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

  const result = streamText({
    model: openai('gpt-4o'),
    messages,
    tools: {
      get_weather: tool({
        description: 'Get current weather for a location',
        parameters: z.object({
          location: z.string().describe('City name'),
          unit: z.enum(['celsius', 'fahrenheit']).default('celsius')
        }),
        execute: async ({ location, unit }) => {
          // Execute server-side (secure API keys)
          const response = await fetch(`https://api.weather.com/...`);
          const data = await response.json();
          return { temperature: data.temp, conditions: data.conditions };
        }
      }),

      search_database: tool({
        description: 'Search internal database',
        parameters: z.object({
          query: z.string()
        }),
        execute: async ({ query }) => {
          // Direct database access (server-side only)
          const results = await db.search(query);
          return results;
        }
      })
    }
  });

  return result.toDataStreamResponse();
}