AI Elements

AI Elements is Vercel’s answer to the repeated problem of rebuilding the same chat UI primitives for every AI product: message bubbles, streaming responses, reasoning traces, tool-call visualizations, and code blocks. Rather than shipping as a traditional npm dependency, it distributes as a shadcn/ui-style registry — running npx ai-elements@latest (or npx ai-elements@latest add <component>) fetches component source from a hosted registry endpoint and pipes it through the shadcn CLI, copying the actual .tsx source into the consumer’s own components/ai-elements/ directory rather than installing an opaque compiled package.

The component set (over 45 components spanning conversation containers, messages, reasoning displays, tool/agent visualizations, code blocks, canvases, file trees, terminals, and audio/voice pickers) is purpose-built for apps using the AI SDK’s useChat hook and UIMessage types, so components like Message and Response consume AI SDK primitives directly rather than generic props. Because the code lands in the consumer’s own tree, teams get full customization without maintaining a fork, at the cost of manual updates when AI Elements ships new versions.

What You Get

• A CLI (npx ai-elements@latest) that installs all components, or add <component> to install one at a time, auto-detecting npm/pnpm/yarn/bun
• 45+ React components covering chat UI (message, conversation, prompt-input, response), agent/tool visualization (tool, agent, plan, chain-of-thought, task), and rich content (code-block, terminal, file-tree, canvas, artifact)
• Deep integration with the Vercel AI SDK — components consume UIMessage and useChat types directly instead of generic props
• Full source-code ownership: components are copied into your own components/ai-elements/ directory via the shadcn/ui CLI, so they’re yours to modify
• A hosted component registry (elements.ai-sdk.dev/api/registry) that the CLI and the standard shadcn CLI can both consume

Common Use Cases

• Bootstrapping a chat UI for a Next.js + AI SDK application without hand-building message bubbles and streaming states
• Adding reasoning/tool-call visualization to an agentic product so users can see what the model is doing, not just its final answer
• Building AI coding-assistant style UIs that need code blocks, diffs, file trees, and terminal output components
• Standardizing chat UI primitives across multiple internal AI products on one shadcn/ui-based design system
• Prototyping AI product UIs quickly, then customizing the copied component source once product requirements diverge from the defaults

Under The Hood

Architecture The published ai-elements npm package is deliberately thin: packages/cli/index.js is a ~60-line Node script with no runtime dependencies that detects the invoking package manager from npm_config_user_agent, resolves one or more component names to registry JSON URLs under https://elements.ai-sdk.dev/api/registry/, and shells out to shadcn@latest add <urls> via spawnSync. The real component implementations live in a sibling, unpublished workspace package (@repo/elements, in packages/elements/src) as 45+ standalone .tsx files (message, conversation, tool, agent, chain-of-thought, code-block, terminal, canvas, and more), each exporting typed, composable pieces rather than one monolithic component. The docs app (apps/docs) serves the registry manifest that both this CLI and the standard shadcn CLI consume, so the actual delivery mechanism is copy-on-install: nothing from @repo/elements ships as compiled JS in the npm tarball — the CLI’s only job is to hand the shadcn CLI a URL.

Tech Stack A pnpm/Turborepo monorepo (turbo.json, pnpm-workspace.yaml) with the published CLI package built on plain Node.js child_process, while the component package it fetches from targets React 19 and Next.js/AI SDK consumers. Components lean on @repo/shadcn-ui (the project’s local shadcn/ui fork), class-variance-authority for variant styling, streamdown (with @streamdown/code, @streamdown/math, @streamdown/mermaid, @streamdown/cjk plugins) for streaming markdown rendering, shiki for syntax highlighting, @xyflow/react for the canvas/node/edge flow components, and the ai package’s UIMessage types for AI SDK integration. Linting/formatting run through oxlint/oxfmt via ultracite, and releases are managed with Changesets.

Code Quality The elements package has a substantial Vitest test suite — a dedicated __tests__ file per component (e.g. message.test.tsx, tool.test.tsx, conversation.test.tsx) using @testing-library/react and browser-mode Vitest with Playwright, plus vitest-fail-on-console to catch console noise during tests. Components are fully typed (exported prop types per component, e.g. MessageProps, MessageContentProps), and the published CLI script itself has no tests of its own beyond its trivial branching logic, which is consistent with its small surface area. CI runs on GitHub Actions (test.yml) and a bot-driven skills-generation workflow keeps a Claude-skills mirror of the docs in sync.

What Makes It Unique Most component libraries either publish compiled JS to npm or vendor a copy-paste snippet site; AI Elements’ CLI does neither — it’s a thin dispatcher that hands the shadcn CLI a URL, meaning the actual component surface can evolve on the registry server without a version bump to the installed code, while consumers still get real, editable source in their own tree. Pairing that distribution model tightly with AI SDK types (rather than generic chat props) and extending shadcn/ui’s usual form/nav/dialog component set into agent-specific primitives (tool calls, chain-of-thought, task tracking, plan visualization) is the more novel part technically — it treats “agent transparency UI” as a first-class component category rather than something every team builds ad hoc.