elements

assistant-ui Elements

请始终查阅 assistant-ui.com/llms.txt，了解最新的 API。

Elements 是构建在无样式原语之上的样式化组件，可直接复制到你的项目中。每个 Element 都是一个 TSX 文件，CLI 会将其复制到 components/assistant-ui/elements/，因此源码由你掌控，可直接在原处自定义。assistant-ui.com/elements 中的目录为每个 Element 提供实时演示、运行时配方和独立配方。

参考资料

• ./references/catalog.md -- 按类别列出每个 Element 及其注册表项目和已安装文件
• ./references/aui-elements.md -- 与运行时连接的 Elements（Thread、ThreadList、AssistantModal、AssistantSidebar、ToolFallback、ToolGroup、Reasoning、Sources、Attachment、ModelSelector、Voice、McpConfig 及渲染器）
• ./references/standalone-elements.md -- 按类别分组的属性驱动 Elements，以及重要的属性结构

两种 Element

类型	文件	是否需要运行时	注册表项目
与运行时连接	elements/<name>.aui.tsx	是，读取最近的 AssistantRuntimeProvider	简称：thread、thread-list、tool-fallback、reasoning、...
独立	elements/<name>.tsx	否，所有内容都通过属性传入	elements-<slug>：elements-agent-plan、elements-code-diff、...
渲染器	elements/<name>.tsx	通过 .aui Element 或工具包的 render 使用	markdown-text、syntax-highlighter、shiki-highlighter、mermaid-diagram、generative-ui

有些 Element 同时提供两种形式。thread-list 安装与运行时连接的侧边栏列表，elements-thread-list 安装属性驱动的版本；reasoning、sources、tool-group、model-selector、message-timing、context-display、voice（圆球）、attachment（elements-message-attachment）、quote（elements-quote-reply）和 follow-up-suggestions（elements-suggestions）也采用相同的区分方式。若数据已在会话中，请选择 .aui；若要使用自己的状态、工具结果或设计稿进行渲染，请选择独立版本。

安装

npx assistant-ui@latest init                 # once per project: components.json, style, base elements
npx assistant-ui@latest add thread thread-list
npx assistant-ui@latest add elements-agent-plan elements-code-diff

add 会封装 npx shadcn@latest add，并附上注册表 URL，同时拉取注册表依赖项（例如，thread 会引入 markdown-text、tool-fallback、tool-group、reasoning、sources、attachment、image、file、follow-up-suggestions、tooltip-icon-button）和 npm 依赖项（@assistant-ui/react、lucide-react、tw-shimmer）。独立 Elements 会引入 elements-surfaces，以使用共享令牌。

如果没有 components.json，CLI 会发出警告并安装 Base UI 版本。若要让 shadcn CLI 直接解析 Elements，请注册支持样式的 URL：

{
  "registries": {
    "@assistant-ui": "https://r.assistant-ui.com/styles/{style}/{name}.json"
  }
}

之后，npx shadcn@latest add @assistant-ui/thread 也能正常使用。名为 base-* 的样式会采用 Base UI 版本；其他所有样式都会采用 Radix。大多数 Elements 只组合 @assistant-ui/react 原语，并使用同一份源码支持两者；涉及特定库界面（tooltip-icon-button、attachment、context-display、message-timing、mcp-config、threadlist-sidebar、assistant-modal、model-selector 以及共享的 select、tabs、accordion、badge、direction）的 Elements 则提供专用的 Base UI 版本。普通的 https://r.assistant-ui.com/{name}.json URL 仍会回退到 Radix。

使用与运行时连接的 Element

"use client";

import { AssistantRuntimeProvider } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/ai-sdk";
import { Thread } from "@/components/assistant-ui/elements/thread.aui";
import { ThreadList } from "@/components/assistant-ui/elements/thread-list.aui";

export default function Chat() {
  const runtime = useChatRuntime();
  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <div className="flex h-dvh">
        <ThreadList />
        <Thread />
      </div>
    </AssistantRuntimeProvider>
  );
}

Thread 不接受运行时属性；它会读取最近的 Provider。它会渲染欢迎屏幕、切换会话加载期间的历史记录骨架屏、消息列表、滚动到底部按钮、后续建议和消息输入框。

覆盖插槽，而不是分叉文件

import { Thread, type ThreadComponents } from "@/components/assistant-ui/elements/thread.aui";

const THREAD_COMPONENTS: ThreadComponents = {
  Welcome: () => <h1 className="text-2xl">Ask me anything</h1>,
  ToolFallback: MyToolFallback,
};

export function Chat() {
  return <Thread components={THREAD_COMPONENTS} autoFocus={false} />;
}

插槽：AssistantMessage、Welcome、ToolFallback、ToolGroup、ReasoningGroup。请在模块作用域定义该对象，或使用 memoize 缓存它；否则，每次父组件渲染都会重新挂载消息子树。对于按工具定制的 UI，请在工具包条目上注册 render（参见 tools），而不是覆盖 ToolFallback；按名称注册的工具 UI 优先于插槽。

重新设置样式

Thread 会在 ThreadPrimitive.Root 上以内联方式设置 --thread-max-width、--composer-bg、--composer-radius 和 --composer-padding，因此请编辑你自己的 thread.aui.tsx 副本来修改这些值，而不是从外层类修改。副本中的其他内容都使用 Tailwind。

使用独立元素

import { AgentPlan } from "@/components/assistant-ui/elements/agent-plan";

<AgentPlan
  steps={["Read the schema", "Write the migration", "Run the tests"]}
  activeIndex={1}
/>;

独立元素接收普通属性（此处为 steps: readonly string[] 和 activeIndex: number，以及任意 div 属性），且不会读取运行时状态，因此可用于工具 render、仪表板或 Storybook。每个目录页面的“Standalone”标签页都会显示确切的属性结构；独立元素参考总结了最常用的元素。

共享表面设计令牌

elements-surfaces 会安装 components/assistant-ui/elements/surfaces.tsx，其中包含一组类名字符串常量和两个辅助函数，为所有元素提供统一外观：paper 和 floating（卡片与弹出层填充色）、field 和 fieldInteractive（输入框）、pressable、ghostButton、inkButton、mono、live（流式传输强调色）、iconSwap 和 labelSwap 过渡效果、collapsePanel、codeScroll 和 codeSurface，以及 ShimmerLabel 和 SwapLabel。在自定义组件中通过 @/lib/utils 中的 cn(...) 复用这些样式（如果缺少 lib/utils.ts，CLI 会生成该文件），让自定义 UI 与目录中的样式保持一致。

常见问题

Cannot find module '@/components/assistant-ui/thread'

• 元素已移至 elements/ 下，与运行时连接的文件带有 .aui 后缀：@/components/assistant-ui/elements/thread.aui。渲染器和独立元素没有后缀。

元素能够渲染，但没有样式

• 注册表假定使用 Tailwind v4 和 globals.css 中的 shadcn 主题变量（@import "tailwindcss"，以及 --background、--foreground、--border 系列变量）。npx assistant-ui@latest init 会写入这些变量；在手动搭建的项目中，请从 create 脚手架复制这些变量。

CLI 安装了错误的样式版本

• add 会读取 components.json 的 style 字段；base-* 样式使用 Base UI，其他样式使用 Radix。修正样式后，使用 --overwrite 重新添加。

Thread 在每次父组件渲染时都会重新渲染所有消息

• components 属性对象是在行内创建的。请将它提升到模块作用域，或使用 useMemo。

.aui 元素因缺少 provider 而报错

• 它必须是 AssistantRuntimeProvider 的后代（或位于一个配置提供了它读取的作用域的 AuiProvider 下）。独立元素没有此要求。

找不到注册表条目

• 与运行时连接的条目和渲染器条目使用短名称（thread、markdown-text）；独立条目带有 elements- 前缀（elements-agent-plan）。目录列出了每个元素对应的确切条目。

相关技能

• primitives -- .aui 元素组合使用的无样式基础组件
• setup -- create、init 及 CLI 的其他功能
• tools -- 用于按工具替换 ToolFallback 的工具包 render 条目
• generative-ui -- generative-ui 渲染器和组件词汇表
• markdown -- markdown-text、shiki-highlighter、syntax-highlighter、mermaid-diagram
• thread-list -- thread-list、threadlist-sidebar、thread-search、conversation-map