ai-elements-chatbot

What this skill does

# AI Elements Chatbot Components

**Status**: Production Ready
**Last Updated**: 2025-11-07
**Dependencies**: tailwind-v4-shadcn (prerequisite), ai-sdk-ui (companion), nextjs (framework)
**Latest Versions**: [email protected], [email protected]+, next@15+, react@19+

---

## Quick Start (15 Minutes)

### 1. Verify Prerequisites

Before installing AI Elements, ensure these are already set up:

```bash
# Check Next.js version (needs 15+)
npx next --version

# Check AI SDK version (needs 5+)
npm list ai

# Check shadcn/ui is initialized
ls components/ui  # Should exist with button.tsx etc
```

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

### 2. Install AI Elements CLI

```bash
# Initialize AI Elements in your project
pnpm dlx ai-elements@latest init

# Add your first components
pnpm dlx ai-elements@latest add message conversation response prompt-input
```

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

### 3. Create Basic Chat Interface

```typescript
// 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>
  );
}
```

Done! You now have a working chat interface with:
- ✅ Streaming markdown rendering
- ✅ Auto-scrolling conversation
- ✅ Auto-resizing input
- ✅ Role-based message styling

---

## The 5-Step Setup Process

### Step 1: Install AI Elements CLI

```bash
pnpm dlx ai-elements@latest init
```

This:
- Creates `components/ui/ai/` directory
- Updates `components.json` with AI Elements registry
- Adds necessary dependencies to package.json

**Key Points:**
- Run from project root (where package.json is)
- Requires shadcn/ui already initialized
- Will fail if `components.json` missing (run `pnpm dlx shadcn@latest init` first)

### Step 2: Add Core Chat Components

```bash
# Essential components for basic chat
pnpm dlx ai-elements@latest add message message-content conversation response

# Optional: Input component
pnpm dlx ai-elements@latest add prompt-input actions suggestion
```

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

### Step 3: Add Advanced Components (Optional)

```bash
# For tool calling
pnpm dlx ai-elements@latest add tool

# For reasoning display (Claude/o1 style)
pnpm dlx ai-elements@latest add reasoning

# For source citations (Perplexity style)
pnpm dlx ai-elements@latest add sources inline-citation

# For code highlighting
pnpm dlx ai-elements@latest add code-block

# For conversation branching
pnpm dlx ai-elements@latest add branch

# For task lists
pnpm dlx ai-elements@latest add task

# For AI-generated images
pnpm dlx ai-elements@latest add image

# For web previews (Claude artifacts style)
pnpm dlx ai-elements@latest add web-preview

# For loading states
pnpm dlx ai-elements@latest add loader
```

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

### Step 4: Create API Route

Create `/app/api/chat/route.ts`:

```typescript
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();
}
```

**Key Points:**
- Must use AI SDK v5 `streamText()` (not v4 `OpenAIStream()`)
- Returns `toDataStreamResponse()` for streaming
- Client auto-receives updates via `useChat()` hook

### Step 5: Verify Installation

```bash
# Check components installed
ls components/ui/ai/

# Expected output:
# message.tsx, message-content.tsx, conversation.tsx, response.tsx, prompt-input.tsx, ...

# Start dev server
pnpm dev

# Test chat interface at http://localhost:3000/chat
```

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

---

## Critical Rules

### Always Do

✅ **Initialize shadcn/ui BEFORE AI Elements** - AI Elements requires shadcn/ui as foundation
✅ **Use AI SDK v5** - v4 is incompatible (breaking changes)
✅ **Use Next.js App Router** - Pages Router not supported
✅ **Wrap with `'use client'`** - All AI Elements components are client-side
✅ **Pass raw markdown to Response component** - Not pre-rendered HTML
✅ **Use Conversation component as container** - Handles auto-scroll and virtualization
✅ **Conditionally show voice input** - Only works in Chrome/Edge (not Firefox/Safari)
✅ **Merge consecutive reasoning blocks** - Prevent duplication in long responses

### Never Do

❌ **Install AI Elements as npm package** - It's a CLI tool that copies components
❌ **Use with AI SDK v4** - Will fail with type errors and data format issues
❌ **Forget `'use client'` directive** - Components use React hooks (client-only)
❌ **Mix with other component libraries** - Built for shadcn/ui only (Tailwind classes)
❌ **Manually write component code** - Use CLI to ensure correct patterns
❌ **Skip prerequisites check** - Will fail silently with confusing errors
❌ **Use in Pages Router** - Requires App Router features
❌ **Assume voice input works everywhere** - Web Speech API is Chrome/Edge only

---

## Known Issues Prevention

This skill prevents **8** documented issues:

### Issue #1: PromptInputSpeechButton Not Working (Firefox/Safari)
**Error**: Voice input button doesn't respond or throws `SpeechRecognition is not defined`
**Source**: https://github.com/vercel/ai-elements/issues/210
**Why It Happens**: Web Speech API only supported in Chromium browsers (Chrome, Edge)
**Prevention**:
```tsx
// 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)
/>
```

### Issue #2: PromptInput Not Respon