ai-elements

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# AI Elements

> **CRITICAL — Your training data is outdated for this library.** AI Elements is a new component registry (2025+) that is not in your training data. Before using AI Elements, **fetch the docs** at https://ai-sdk.dev/elements and the component reference at https://ai-sdk.dev/elements/components to find the correct component names, props, and installation commands. Install components via `npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/<component>.json` — do not create these components from scratch.

You are an expert in AI Elements — a component library and custom shadcn/ui registry built on top of shadcn/ui to help you build AI-native applications faster. AI Elements provides 40+ production-ready React components specifically designed for AI interfaces.

## Overview

**AI Elements is mandatory for any project that displays AI-generated text.** Install it immediately after scaffolding — do not build chat UIs or AI text displays from scratch. Without AI Elements, AI-generated markdown renders as ugly raw text with visible `**`, `##`, `---` characters.

Unlike regular UI libraries, AI Elements understands AI-specific patterns — message parts, streaming states, tool calls, reasoning displays, and markdown rendering. Components are tightly integrated with AI SDK hooks like `useChat` and handle the unique challenges of streaming AI responses.

The CLI adds components directly to your codebase with full source code access — no hidden dependencies, fully customizable.

## Type Errors in AI Elements

**NEVER add `@ts-nocheck` to AI Elements files.** If `next build` reports a type error in an AI Elements component (e.g. `plan.tsx`, `toolbar.tsx`), the cause is a version mismatch between the component and its dependencies (`@base-ui/react`, shadcn/ui `Button`, etc.).

**Fix**:
1. Reinstall the broken component: `npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/<component>.json --overwrite`
2. If that fails, update the conflicting dep: `npm install @base-ui/react@latest`
3. Only if the component is truly unused, delete it — don't suppress its types

Adding `@ts-nocheck` hides real bugs and breaks IDE support for the entire file.

**Install only the components you need** — do NOT install the full suite:
```bash
npx ai-elements@latest add message          # MessageResponse for markdown rendering
npx ai-elements@latest add conversation     # Full chat UI (if building a chat app)
```

## Rendering Any AI-Generated Markdown

**`<MessageResponse>` is the universal markdown renderer.** Use it for ANY AI-generated text — not just chat messages. It's exported from `@/components/ai-elements/message` and wraps Streamdown with code highlighting, math, mermaid, and CJK plugins.

```tsx
import { MessageResponse } from "@/components/ai-elements/message";

// Workflow event with markdown content
<MessageResponse>{event.briefing}</MessageResponse>

// Any AI-generated string
<MessageResponse>{generatedReport}</MessageResponse>

// Streaming text from getWritable events
<MessageResponse>{narrativeText}</MessageResponse>
```

**Never render AI text as raw JSX** like `{event.content}` or `<p>{text}</p>` — this displays ugly unformatted markdown with visible `**`, `##`, `---`. Always wrap in `<MessageResponse>`.

This applies everywhere AI text appears: workflow event displays, briefing panels, reports, narrative streams, notifications, email previews.

## Design Direction for AI Interfaces

AI Elements solves message rendering, not the whole product aesthetic. Surround it with shadcn + Geist discipline. Use Conversation/Message for the stream area, compose the rest with shadcn primitives. Use Geist Sans for conversational UI, Geist Mono for tool args/JSON/code/timestamps. Default to dark mode for AI products. Avoid generic AI styling: purple gradients, glassmorphism everywhere, over-animated status indicators.

## Installation

**Install only the components you actually use.** Do NOT run `npx ai-elements@latest` without arguments or install `all.json` — this installs 48 components, most of which you won't need, and may introduce type conflicts between unused components and your dependency versions.

```bash
# Install specific components (RECOMMENDED)
npx ai-elements@latest add message          # MessageResponse — required for any AI text
npx ai-elements@latest add conversation     # Full chat UI container
npx ai-elements@latest add code-block       # Syntax-highlighted code
npx ai-elements@latest add tool             # Tool call display

# Or use shadcn CLI directly with the registry URL
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/message.json
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/conversation.json
```

**Never install all.json** — it pulls in 48 components including ones with `@base-ui/react` dependencies that may conflict with your shadcn version.

Components are installed into `src/components/ai-elements/` by default.

## Key Components

### Conversation + Message (Core)

The most commonly used components for building chat interfaces:

```tsx
'use client'
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from 'ai'
import { Conversation } from '@/components/ai-elements/conversation'
import { Message } from '@/components/ai-elements/message'

export function Chat() {
  const { messages, sendMessage, status } = useChat({
    transport: new DefaultChatTransport({ api: '/api/chat' }),
  })

  return (
    <Conversation>
      {messages.map((message) => (
        <Message key={message.id} message={message} />
      ))}
    </Conversation>
  )
}
```

The `Conversation` component wraps messages with auto-scrolling and a scroll-to-bottom button.

The `Message` component renders message parts automatically — text, tool calls, reasoning, images — without manual part-type checking.

### Message Markdown

The `MessageMarkdown` sub-component is optimized for streaming — it efficiently handles incremental markdown updates without re-parsing the entire content on each stream chunk:

```tsx
import { MessageMarkdown } from '@/components/ai-elements/message'

// Inside a custom message renderer
<MessageMarkdown content={part.text} />
```

From trancethehuman/template-next-agent, AGPL-3.0.

More from trancethehuman/template-next-agent