ai-elements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Elements

AI Elements is a component library and custom registry built on top of shadcn/ui to help you build AI-native applications faster. It provides pre-built components like conversations, messages and more.

Installing AI Elements is straightforward and can be done in a couple of ways. You can use the dedicated CLI command for the fastest setup, or integrate via the standard shadcn/ui CLI if you've already adopted shadcn's workflow.

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

安装AI Elements非常简单，有几种方式可选。你可以使用专用的CLI命令实现最快设置，如果你已经采用了shadcn的工作流，也可以通过标准的shadcn/ui CLI进行集成。

Quick Start

快速开始

Here are some basic examples of what you can achieve using components from AI Elements.

以下是使用AI Elements组件可实现的一些基础示例。

Prerequisites

前置要求

Before installing AI Elements, make sure your environment meets the following requirements:

Node.js, version 18 or later
A Next.js project with the AI SDK installed.
shadcn/ui installed in your project. If you don't have it installed, running any install command will automatically install it for you.
We also highly recommend using the AI Gateway and adding
```
AI_GATEWAY_API_KEY
```
to your
```
env.local
```
so you don't have to use an API key from every provider. AI Gateway also gives $5 in usage per month so you can experiment with models. You can obtain an API key here.

在安装AI Elements之前，请确保你的环境满足以下要求：

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

Installing Components

安装组件

You can install AI Elements components using either the AI Elements CLI or the shadcn/ui CLI. Both achieve the same result: adding the selected component’s code and any needed dependencies to your project.

The CLI will download the component’s code and integrate it into your project’s directory (usually under your components folder). By default, AI Elements components are added to the

@/components/ai-elements/

directory (or whatever folder you’ve configured in your shadcn components settings).

After running the command, you should see a confirmation in your terminal that the files were added. You can then proceed to use the component in your code.

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

CLI会下载组件代码并将其集成到项目目录中（通常在你的components文件夹下）。默认情况下，AI Elements组件会被添加到

@/components/ai-elements/

目录（或你在shadcn组件设置中配置的任何文件夹）。

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

Usage

使用方法

Once an AI Elements component is installed, you can import it and use it in your application like any other React component. The components are added as part of your codebase (not hidden in a library), so the usage feels very natural.

安装AI Elements组件后，你可以像导入其他React组件一样导入并在应用中使用它。这些组件会被添加到你的代码库中（而非隐藏在某个库中），因此使用起来非常自然。

Example

示例

After installing AI Elements components, you can use them in your application like any other React component. For example:

tsx

'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;

In the example above, we import the

Message

component from our AI Elements directory and include it in our JSX. Then, we compose the component with the

MessageContent

and

MessageResponse

subcomponents. You can style or configure the component just as you would if you wrote it yourself – since the code lives in your project, you can even open the component file to see how it works or make custom modifications.

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

tsx

'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

子组件组合使用。你可以像自己编写的组件一样对其进行样式设置或配置——由于代码位于你的项目中，你甚至可以打开组件文件查看其工作原理或进行自定义修改。

Extensibility

可扩展性

All AI Elements components take as many primitive attributes as possible. For example, the

Message

component extends

HTMLAttributes<HTMLDivElement>

, so you can pass any props that a

div

supports. This makes it easy to extend the component with your own styles or functionality.

所有AI Elements组件都支持尽可能多的原生属性。例如，

Message

组件继承了

HTMLAttributes<HTMLDivElement>

，因此你可以传递任何

div

支持的props。这使得你可以轻松地用自己的样式或功能扩展组件。

Customization

自定义

After installation, no additional setup is needed. The component’s styles (Tailwind CSS classes) and scripts are already integrated. You can start interacting with the component in your app immediately.

For example, if you'd like to remove the rounding on

Message

, you can go to

components/ai-elements/message.tsx

and remove

rounded-lg

as follows:

tsx

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 CSS类）和脚本已完成集成。你可以立即开始在应用中使用该组件。

例如，如果你想移除

Message

组件的圆角，可以打开

components/ai-elements/message.tsx

并删除

rounded-lg

，如下所示：

tsx

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>
);

Troubleshooting

故障排除

Why are my components not styled?

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

Make sure your project is configured correctly for shadcn/ui in Tailwind 4 - this means having a

globals.css

file that imports Tailwind and includes the shadcn/ui base styles.

请确保你的项目针对Tailwind 4的shadcn/ui配置正确——这意味着你需要有一个

globals.css

文件，其中导入了Tailwind并包含shadcn/ui的基础样式。

I ran the AI Elements CLI but nothing was added to my project

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

Double-check that:

Your current working directory is the root of your project (where
```
package.json
```
lives).
Your components.json file (if using shadcn-style config) is set up correctly.
You’re using the latest version of the AI Elements CLI:

bash

npx ai-elements@latest

If all else fails, feel free to open an issue on GitHub.

请仔细检查：

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

bash

npx ai-elements@latest

如果以上都没问题，欢迎在GitHub上提交issue。

Theme switching doesn’t work — my app stays in light mode

主题切换不起作用——我的应用一直停留在浅色模式

Ensure your app is using the same data-theme system that shadcn/ui and AI Elements expect. The default implementation toggles a data-theme attribute on the

<html>

element. Make sure your tailwind.config.js is using class or data- selectors accordingly:

请确保你的应用使用的是shadcn/ui和AI Elements期望的data-theme系统。默认实现会切换

<html>

元素上的data-theme属性。请确保你的tailwind.config.js相应地使用了类选择器或data-选择器：

The component imports fail with “module not found”

组件导入失败，提示“模块未找到”

Check the file exists. If it does, make sure your

tsconfig.json

has a proper paths alias for

@/

i.e.

json

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

检查文件是否存在。如果存在，请确保你的

tsconfig.json

为

@/

配置了正确的路径别名，例如：

json

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

My AI coding assistant can't access AI Elements components

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

Verify your config file syntax is valid JSON.
Check that the file path is correct for your AI tool.
Restart your coding assistant after making changes.
Ensure you have a stable internet connection.

验证你的配置文件语法是有效的JSON。
检查你的AI工具对应的文件路径是否正确。
更改配置后重启你的代码助手。
确保你的网络连接稳定。

Still stuck?

仍然遇到问题？

If none of these answers help, open an issue on GitHub and someone will be happy to assist.

如果以上解决方案都无法解决你的问题，请在GitHub上提交issue，我们会很乐意提供帮助。

Available Components

可用组件

See the

references/

folder for detailed documentation on each component.

有关每个组件的详细文档，请查看

references/

文件夹。