|
| 1 | +--- |
| 2 | +name: AI Elements Usage Guide |
| 3 | +description: A comprehensive guide on using AI Elements for building AI-native applications. |
| 4 | +glob: ["app/**/*", "ui/**/*", "src/components/**/*"] |
| 5 | +tags: ["AI", "Elements", "shadcn/ui", "React", "Tailwind CSS", "AI SDK"] |
| 6 | +--- |
| 7 | +# AI Elements Usage Guide |
| 8 | + |
| 9 | +This document provides comprehensive guidance on using AI Elements, a component library built on shadcn/ui for building AI-native applications. Based on the official documentation at https://ai-sdk.dev/elements and https://ai-sdk.dev/elements/usage. |
| 10 | + |
| 11 | +## What is AI Elements? |
| 12 | + |
| 13 | +AI Elements is a component library and custom registry built on top of [shadcn/ui](https://ui.shadcn.com/) to help you build AI-native applications faster. It provides pre-built components like conversations, messages, and more. |
| 14 | + |
| 15 | +## Prerequisites |
| 16 | + |
| 17 | +Before installing AI Elements, ensure your environment meets these requirements: |
| 18 | + |
| 19 | +- **Node.js**: Version 18 or later |
| 20 | +- **Next.js project**: With the [AI SDK](https://ai-sdk.dev/) installed |
| 21 | +- **shadcn/ui**: Installed in your project (will be auto-installed if missing) |
| 22 | +- **AI Gateway** (recommended): Add `AI_GATEWAY_API_KEY` to your `.env.local` for $5/month free usage |
| 23 | + |
| 24 | +AI Elements targets React 19 and Tailwind CSS 4. |
| 25 | + |
| 26 | +## Installation |
| 27 | + |
| 28 | +### Using AI Elements CLI (Recommended) |
| 29 | + |
| 30 | +```bash |
| 31 | +npx ai-elements@latest |
| 32 | +``` |
| 33 | + |
| 34 | +### Using shadcn/ui CLI |
| 35 | + |
| 36 | +```bash |
| 37 | +npx shadcn@latest add --registry ai-elements |
| 38 | +``` |
| 39 | + |
| 40 | +Components are installed to `@/components/ai-elements/` by default. The CLI downloads component code and integrates it into your project. |
| 41 | + |
| 42 | +## Quick Start Examples |
| 43 | + |
| 44 | +AI Elements enables building sophisticated AI interfaces: |
| 45 | + |
| 46 | +- **Chat interfaces** with streaming responses |
| 47 | +- **Multi-modal interactions** (text, voice, attachments) |
| 48 | +- **Workflow visualizations** |
| 49 | +- **Real-time data processing** displays |
| 50 | +- **Context-aware conversations** |
| 51 | + |
| 52 | +## Usage |
| 53 | + |
| 54 | +### Basic Example |
| 55 | + |
| 56 | +After installation, use components like any React component: |
| 57 | + |
| 58 | +```typescript |
| 59 | +"use client" |
| 60 | + |
| 61 | +import { |
| 62 | + Message, |
| 63 | + MessageContent, |
| 64 | + MessageResponse, |
| 65 | +} from '@/components/ai-elements/message' |
| 66 | +import { useChat } from '@ai-sdk/react' |
| 67 | + |
| 68 | +const Example = () => { |
| 69 | + const { messages } = useChat() |
| 70 | + |
| 71 | + return ( |
| 72 | + <> |
| 73 | + {messages.map(({ role, parts }, index) => ( |
| 74 | + <Message from={role} key={index}> |
| 75 | + <MessageContent> |
| 76 | + {parts.map((part, i) => { |
| 77 | + switch (part.type) { |
| 78 | + case 'text': |
| 79 | + return <MessageResponse key={`${role}-${i}`}>{part.text}</MessageResponse> |
| 80 | + } |
| 81 | + })} |
| 82 | + </MessageContent> |
| 83 | + </Message> |
| 84 | + ))} |
| 85 | + </> |
| 86 | + ) |
| 87 | +} |
| 88 | + |
| 89 | +export default Example |
| 90 | +``` |
| 91 | + |
| 92 | +## Component Categories |
| 93 | + |
| 94 | +### Chatbot Components |
| 95 | + |
| 96 | +- **Chain of Thought**: Display reasoning processes |
| 97 | +- **Checkpoint**: Save/restore conversation states |
| 98 | +- **Confirmation**: Handle user confirmations |
| 99 | +- **Conversation**: Main chat container |
| 100 | +- **Context**: Display relevant context |
| 101 | +- **Inline Citation**: Reference sources |
| 102 | +- **Message**: Individual message component |
| 103 | +- **Model Selector**: Choose AI models |
| 104 | +- **Plan**: Show execution plans |
| 105 | +- **Prompt Input**: Enhanced input field |
| 106 | +- **Queue**: Manage queued tasks |
| 107 | +- **Reasoning**: Display AI reasoning |
| 108 | +- **Shimmer**: Loading animations |
| 109 | +- **Sources**: Display source citations |
| 110 | +- **Suggestions**: Offer follow-up prompts |
| 111 | +- **Task**: Track task progress |
| 112 | +- **Tool**: Display tool usage |
| 113 | + |
| 114 | +### Workflow Components |
| 115 | + |
| 116 | +- **Canvas**: Visual workflow editor |
| 117 | +- **Connection**: Connect workflow nodes |
| 118 | +- **Controls**: Workflow controls |
| 119 | +- **Edge**: Connection lines |
| 120 | +- **Node**: Workflow steps |
| 121 | +- **Panel**: Side panels |
| 122 | +- **Toolbar**: Workflow tools |
| 123 | + |
| 124 | +### Vibe Coding Components |
| 125 | + |
| 126 | +- **Artifact**: Display generated code/content |
| 127 | +- **Web Preview**: Preview generated content |
| 128 | + |
| 129 | +### Documentation Components |
| 130 | + |
| 131 | +- **Open in Chat**: Link to chat interface |
| 132 | + |
| 133 | +### Utilities |
| 134 | + |
| 135 | +- **Code Block**: Syntax-highlighted code |
| 136 | +- **Image**: Enhanced image display |
| 137 | +- **Loader**: Loading indicators |
| 138 | + |
| 139 | +## Extensibility |
| 140 | + |
| 141 | +All AI Elements components extend primitive HTML attributes: |
| 142 | + |
| 143 | +```typescript |
| 144 | +// Message extends HTMLAttributes<HTMLDivElement> |
| 145 | +<Message |
| 146 | + className="custom-styles" |
| 147 | + onClick={handleClick} |
| 148 | + data-testid="message" |
| 149 | +> |
| 150 | + {/* content */} |
| 151 | +</Message> |
| 152 | +``` |
| 153 | + |
| 154 | +## Customization |
| 155 | + |
| 156 | +### Modifying Components |
| 157 | + |
| 158 | +Components are added to your codebase, so you can modify them directly: |
| 159 | + |
| 160 | +```typescript |
| 161 | +// components/ai-elements/message.tsx |
| 162 | +export const MessageContent = ({ |
| 163 | + children, |
| 164 | + className, |
| 165 | + ...props |
| 166 | +}: MessageContentProps) => ( |
| 167 | + <div |
| 168 | + className={cn( |
| 169 | + 'flex flex-col gap-2 text-sm text-foreground', |
| 170 | + // Remove rounded-lg for custom styling |
| 171 | + 'group-[.is-user]:bg-primary group-[.is-user]:text-primary-foreground group-[.is-user]:px-4 group-[.is-user]:py-3', |
| 172 | + className, |
| 173 | + )} |
| 174 | + {...props} |
| 175 | + > |
| 176 | + <div className="is-user:dark">{children}</div> |
| 177 | + </div> |
| 178 | +) |
| 179 | +``` |
| 180 | + |
| 181 | +### Re-installation |
| 182 | + |
| 183 | +When re-installing, the CLI asks before overwriting to preserve custom changes. |
| 184 | + |
| 185 | +## Integration with AI SDK |
| 186 | + |
| 187 | +AI Elements works seamlessly with the AI SDK: |
| 188 | + |
| 189 | +```typescript |
| 190 | +import { useChat } from '@ai-sdk/react' |
| 191 | +import { DefaultChatTransport } from 'ai' |
| 192 | +import { Conversation } from '@/components/ai-elements/conversation' |
| 193 | + |
| 194 | +function ChatApp() { |
| 195 | + const { messages, sendMessage } = useChat({ |
| 196 | + transport: new DefaultChatTransport({ |
| 197 | + api: '/api/chat' |
| 198 | + }) |
| 199 | + }) |
| 200 | + |
| 201 | + return ( |
| 202 | + <Conversation messages={messages} onSend={sendMessage} /> |
| 203 | + ) |
| 204 | +} |
| 205 | +``` |
| 206 | + |
| 207 | +## Advanced Features |
| 208 | + |
| 209 | +### Streaming Support |
| 210 | + |
| 211 | +Components handle real-time streaming data: |
| 212 | + |
| 213 | +```typescript |
| 214 | +const { messages } = useChat() |
| 215 | + |
| 216 | +return ( |
| 217 | + <div> |
| 218 | + {messages.map((message) => ( |
| 219 | + <Message key={message.id} from={message.role}> |
| 220 | + {message.parts?.map((part) => { |
| 221 | + switch (part.type) { |
| 222 | + case 'text': |
| 223 | + return <MessageResponse>{part.text}</MessageResponse> |
| 224 | + case 'reasoning': |
| 225 | + return <Reasoning>{part.text}</Reasoning> |
| 226 | + case 'tool-call': |
| 227 | + return <Tool name={part.toolName} args={part.args} /> |
| 228 | + } |
| 229 | + })} |
| 230 | + </Message> |
| 231 | + ))} |
| 232 | + </div> |
| 233 | +) |
| 234 | +``` |
| 235 | + |
| 236 | +### Multi-modal Interactions |
| 237 | + |
| 238 | +Support for various input types: |
| 239 | + |
| 240 | +```typescript |
| 241 | +<PromptInput |
| 242 | + onSend={sendMessage} |
| 243 | + supportsAttachments={true} |
| 244 | + supportsVoice={true} |
| 245 | + placeholder="Ask me anything..." |
| 246 | +/> |
| 247 | +``` |
| 248 | + |
| 249 | +## Best Practices |
| 250 | + |
| 251 | +### Component Composition |
| 252 | + |
| 253 | +Compose components for complex UIs: |
| 254 | + |
| 255 | +```typescript |
| 256 | +const ChatInterface = () => ( |
| 257 | + <Conversation> |
| 258 | + <ModelSelector /> |
| 259 | + <PromptInput /> |
| 260 | + <div className="messages"> |
| 261 | + {/* Message components */} |
| 262 | + </div> |
| 263 | + <Suggestions /> |
| 264 | + </Conversation> |
| 265 | +) |
| 266 | +``` |
| 267 | + |
| 268 | +### Styling |
| 269 | + |
| 270 | +Use Tailwind classes for customization: |
| 271 | + |
| 272 | +```typescript |
| 273 | +<Message |
| 274 | + className="border-2 border-blue-500 rounded-xl shadow-lg" |
| 275 | +/> |
| 276 | +``` |
| 277 | + |
| 278 | +### Performance |
| 279 | + |
| 280 | +Components are optimized for performance with proper memoization and minimal re-renders. |
| 281 | + |
| 282 | +## Troubleshooting |
| 283 | + |
| 284 | +If you encounter issues: |
| 285 | + |
| 286 | +1. Ensure all prerequisites are met |
| 287 | +2. Check that shadcn/ui is properly configured |
| 288 | +3. Verify AI SDK installation |
| 289 | +4. Clear node_modules and reinstall if needed |
| 290 | + |
| 291 | +## Examples |
| 292 | + |
| 293 | +- [Chatbot Example](https://ai-sdk.dev/elements/examples/chatbot) |
| 294 | +- [v0 Clone](https://ai-sdk.dev/elements/examples/v0) |
| 295 | +- [Workflow Example](https://ai-sdk.dev/elements/examples/workflow) |
| 296 | + |
| 297 | +## Additional Resources |
| 298 | + |
| 299 | +- [AI SDK Documentation](https://ai-sdk.dev/) |
| 300 | +- [shadcn/ui Documentation](https://ui.shadcn.com/) |
| 301 | +- [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) |
| 302 | +- [AI Elements MCP Server](https://ai-sdk.dev/elements/mcp) |
| 303 | + |
| 304 | +--- |
| 305 | + |
| 306 | +*Last updated: December 8, 2025* |
| 307 | +*Sources: https://ai-sdk.dev/elements, https://ai-sdk.dev/elements/usage* |
0 commit comments