ai-elements

AI Elements

AI Elements 是一个组件库和自定义注册表，基于 shadcn/ui 构建，可帮助你更快地开发 AI 原生应用。它提供对话、消息等预构建组件。

AI Elements 的安装过程很简单，有几种方式可选。你可以使用专用 CLI 命令快速完成设置，也可以通过标准的 shadcn/ui CLI 集成（如果你已经采用 shadcn 的工作流）。

IMPORTANT： 请使用项目的包管理器运行器执行所有 CLI 命令：npx ai-elements@latest、pnpm dlx ai-elements@latest 或 bunx --bun ai-elements@latest，具体取决于项目的 packageManager。以下示例使用 npx ai-elements@latest，请根据项目情况替换为正确的运行器。

前提条件

安装 AI Elements 前，请确保你的环境符合以下要求：

• Node.js，版本 18 或更高
• 已安装 AI SDK 的 Next.js 项目。
• 项目中已安装 shadcn/ui。如果尚未安装，运行任意安装命令时都会自动为你安装。
• 我们也强烈建议使用 AI Gateway，并将 AI_GATEWAY_API_KEY 添加到你的 env.local，这样就不必使用每个提供商的 API 密钥。AI Gateway 每月还提供价值 $5 的使用额度，供你尝试各种模型。你可以在此处获取 API 密钥。

安装组件

你可以使用 AI Elements CLI 或 shadcn/ui CLI 安装 AI Elements 组件。两者的效果相同：将所选组件的代码及其所需依赖添加到项目中。

CLI 会下载组件代码并将其集成到项目目录中（通常位于 components 文件夹下）。默认情况下，AI Elements 组件会添加到 @/components/ai-elements/ 目录（或你在 shadcn 组件设置中配置的文件夹）。

运行命令后，你应该会在终端看到文件已添加的确认信息。然后就可以在代码中使用该组件。

使用方法

安装 AI Elements 组件后，你可以像使用其他 React 组件一样，在应用中导入并使用它。组件会作为代码库的一部分添加（而不是隐藏在某个库中），因此使用起来十分自然。

示例

安装 AI Elements 组件后，你可以像使用其他 React 组件一样，在应用中使用它。例如：

"use client";

import {
  Message,
  MessageContent,
  MessageResponse,
} from "@/components/ai-elements/message";
import { useChat } from "@ai-sdk/react";

const Example = () => {
  const { messages } = useChat();

  return (
    <>
      {messages.map(({ role, parts }, index) => (
        <Message from={role} key={index}>
          <MessageContent>
            {parts.map((part, i) => {
              switch (part.type) {
                case "text":
                  return (
                    <MessageResponse key={`${role}-${i}`}>
                      {part.text}
                    </MessageResponse>
                  );
              }
            })}
          </MessageContent>
        </Message>
      ))}
    </>
  );
};

export default Example;

在上面的示例中，我们从 AI Elements 目录导入 Message 组件，并在 JSX 中使用它。然后，我们将该组件与 MessageContent 和 MessageResponse 子组件组合使用。你可以像自己编写组件那样为其设置样式或配置——由于代码位于你的项目中，你甚至可以打开组件文件了解其工作方式，或进行自定义修改。

可扩展性

所有 AI Elements 组件都尽可能接受原生 HTML 属性。例如，Message 组件扩展了 HTMLAttributes<HTMLDivElement>，因此你可以传入 div 支持的任意 props。这让你可以轻松扩展组件，添加自己的样式或功能。

自定义

安装后无需进行其他设置。组件样式（Tailwind CSS 类）和脚本都已集成。你可以立即在应用中使用该组件。

例如，如果你想移除 Message 的圆角，可以打开 components/ai-elements/message.tsx，并按如下方式移除 rounded-lg：

export const MessageContent = ({
  children,
  className,
  ...props
}: MessageContentProps) => (
  <div
    className={cn(
      "flex flex-col gap-2 text-sm text-foreground",
      "group-[.is-user]:bg-primary group-[.is-user]:text-primary-foreground group-[.is-user]:px-4 group-[.is-user]:py-3",
      className
    )}
    {...props}
  >
    <div className="is-user:dark">{children}</div>
  </div>
);

故障排除

为什么我的组件没有样式？

确保项目已针对 Tailwind 4 中的 shadcn/ui 正确配置——这意味着需要有一个 globals.css 文件，用于导入 Tailwind 并包含 shadcn/ui 基础样式。

我运行了 AI Elements CLI，但项目中没有添加任何内容

请仔细检查：

• 当前工作目录是项目根目录（package.json 所在的位置）。
• components.json 文件（如果使用 shadcn 风格的配置）已正确设置。
• 使用的是最新版本的 AI Elements CLI：

npx ai-elements@latest

如果这些方法都不管用，欢迎在 GitHub 上提交问题。

主题切换不起作用——我的应用一直处于浅色模式

确保应用使用的是 shadcn/ui 和 AI Elements 所需的同一套 data-theme 系统。默认实现会在 <html> 元素上切换 data-theme 属性。请确保 tailwind.config.js 按相应配置使用 class 或 data- 选择器。

导入组件时出现“module not found”错误

检查文件是否存在。如果存在，请确保 tsconfig.json 中为 @/ 配置了正确的路径别名，即：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

我的 AI 编码助手无法访问 AI Elements 组件

1. 确认配置文件语法是有效的 JSON。
2. 检查文件路径是否适用于你的 AI 工具。
3. 修改后重启编码助手。
4. 确保网络连接稳定。

还是无法解决？

如果这些答案都没有帮助，请在 GitHub 上提交问题，我们很乐意为你提供帮助。

可用组件

各组件的详细文档请参阅 references/ 文件夹。