Back to Details

elements

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

assistant-ui Elements

assistant-ui 元素

Always consult assistant-ui.com/llms.txt for the latest API.
Elements are the styled, copy-into-your-project components that sit on top of the unstyled primitives. Every element is a TSX file the CLI copies into 
components/assistant-ui/elements/
, so you own the source and customize it in place. The catalog at assistant-ui.com/elements documents each one with a live demo, a runtime recipe, and a standalone recipe.
请务必查阅assistant-ui.com/llms.txt获取最新API。
元素是基于无样式基础组件（primitives）构建的、可复制到你的项目中的带样式组件。每个元素都是一个TSX文件，由CLI复制到
components/assistant-ui/elements/
目录下，因此你拥有源码所有权并可在原地自定义。assistant-ui.com/elements上的组件库为每个元素提供了实时演示、运行时使用示例和独立使用示例。

References

参考文档

  • ./references/catalog.md -- every element by section with its registry item and installed file
  • ./references/aui-elements.md -- the runtime-connected elements (Thread, ThreadList, AssistantModal, AssistantSidebar, ToolFallback, ToolGroup, Reasoning, Sources, Attachment, ModelSelector, Voice, McpConfig, and the renderers)
  • ./references/standalone-elements.md -- props-driven elements grouped by section, with the prop shapes that matter
  • ./references/catalog.md —— 按分类列出所有元素及其注册表项和安装后的文件
  • ./references/aui-elements.md —— 连接运行时的元素（Thread、ThreadList、AssistantModal、AssistantSidebar、ToolFallback、ToolGroup、Reasoning、Sources、Attachment、ModelSelector、Voice、McpConfig以及渲染器）
  • ./references/standalone-elements.md —— 按分类分组的基于props的元素，包含关键的props结构

Two kinds of element

两种类型的元素

KindFileNeeds a runtimeRegistry item
Runtime-connected
elements/<name>.aui.tsx
Yes, reads the nearest 
AssistantRuntimeProvider
short name: 
thread
, 
thread-list
, 
tool-fallback
, 
reasoning
, ...
Standalone
elements/<name>.tsx
No, everything comes in through props
elements-<slug>
: 
elements-agent-plan
, 
elements-code-diff
, ...
Renderer
elements/<name>.tsx
Used from a 
.aui
element or a toolkit 
render
markdown-text
, 
syntax-highlighter
, 
shiki-highlighter
, 
mermaid-diagram
, 
generative-ui
A few elements exist in both forms. 
thread-list
installs the runtime-connected sidebar list and 
elements-thread-list
installs the props-driven one; the same split applies to 
reasoning
, 
sources
, 
tool-group
, 
model-selector
, 
message-timing
, 
context-display
, 
voice
(the orb), 
attachment
(
elements-message-attachment
), 
quote
(
elements-quote-reply
), and 
follow-up-suggestions
(
elements-suggestions
). Pick 
.aui
when the data is already in the thread; pick standalone when you render from your own state, a tool result, or a design mock.
类型文件需要运行时注册表项
连接运行时
elements/<name>.aui.tsx
是，读取最近的
AssistantRuntimeProvider
短名称：
thread
、
thread-list
、
tool-fallback
、
reasoning
……
独立型
elements/<name>.tsx
否，所有数据通过props传入
elements-<slug>
：
elements-agent-plan
、
elements-code-diff
……
渲染器
elements/<name>.tsx
从
.aui
元素或工具包的
render
方法调用
markdown-text
、
syntax-highlighter
、
shiki-highlighter
、
mermaid-diagram
、
generative-ui
部分元素同时存在两种形式。
thread-list
安装的是连接运行时的侧边栏列表，
elements-thread-list
安装的是基于props的版本；同样的区分适用于
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
版本；当你需要从自有状态、工具结果或设计原型渲染时，选择独立型版本。

Install

安装

bash
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
wraps 
npx shadcn@latest add
with the registry URL, pulls registry dependencies (for example 
thread
brings 
markdown-text
, 
tool-fallback
, 
tool-group
, 
reasoning
, 
sources
, 
attachment
, 
image
, 
file
, 
follow-up-suggestions
, 
tooltip-icon-button
) and npm dependencies (
@assistant-ui/react
, 
lucide-react
, 
tw-shimmer
). Standalone elements pull 
elements-surfaces
for the shared tokens.
Without a 
components.json
the CLI warns and installs the Base UI flavor. To let the shadcn CLI resolve elements directly, register the style-aware URL:
json
{
  "registries": {
    "@assistant-ui": "https://r.assistant-ui.com/styles/{style}/{name}.json"
  }
}
Then 
npx shadcn@latest add @assistant-ui/thread
works too. Styles named 
base-*
receive the Base UI flavor; every other style receives Radix. Most elements compose only 
@assistant-ui/react
primitives and ship one source for both; the ones that touch library-specific surfaces (
tooltip-icon-button
, 
attachment
, 
context-display
, 
message-timing
, 
mcp-config
, 
threadlist-sidebar
, 
assistant-modal
, 
model-selector
, and the shared 
select
, 
tabs
, 
accordion
, 
badge
, 
direction
) have a dedicated Base UI variant. The plain 
https://r.assistant-ui.com/{name}.json
URL stays a Radix fallback.
bash
npx assistant-ui@latest init                 # 每个项目执行一次：生成components.json、样式文件、基础元素
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-surfaces
以使用共享令牌。
如果没有
components.json
，CLI会发出警告并安装Base UI风格。要让shadcn CLI直接解析元素，请注册感知样式的URL：
json
{
  "registries": {
    "@assistant-ui": "https://r.assistant-ui.com/styles/{style}/{name}.json"
  }
}
之后
npx shadcn@latest add @assistant-ui/thread
也可以正常使用。名称为
base-*
的样式会使用Base UI风格；其他所有样式都使用Radix风格。大多数元素仅基于
@assistant-ui/react
基础组件构建，并且为两种风格提供同一源码；那些涉及库特定界面的元素（
tooltip-icon-button
、
attachment
、
context-display
、
message-timing
、
mcp-config
、
threadlist-sidebar
、
assistant-modal
、
model-selector
以及共享的
select
、
tabs
、
accordion
、
badge
、
direction
）有专门的Base UI变体。普通的
https://r.assistant-ui.com/{name}.json
URL会作为Radix风格的 fallback。

Use a runtime-connected element

使用连接运行时的元素

tsx
"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
takes no runtime prop; it reads the nearest provider. It renders the welcome screen, a history skeleton while a switched thread loads, the message list, the scroll-to-bottom pill, follow-up suggestions, and the composer.
tsx
"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
不需要传入runtime属性；它会读取最近的Provider。它会渲染欢迎界面、切换线程加载时的历史骨架、消息列表、滚动到底部按钮、后续建议和编辑器。

Override a slot instead of forking the file

覆盖插槽而非修改文件

tsx
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} />;
}
Slots: 
AssistantMessage
, 
Welcome
, 
ToolFallback
, 
ToolGroup
, 
ReasoningGroup
. Define the object at module scope or memoize it, otherwise every parent render remounts the message subtrees. For per-tool UI, register 
render
on the toolkit entry (see tools) rather than overriding 
ToolFallback
; a tool UI registered by name wins over the slot.
tsx
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
。请在模块作用域定义该对象或使用
useMemo
缓存，否则父组件每次渲染都会重新挂载消息子树。如需为特定工具设置UI，请在工具包条目上注册
render
方法（参见tools），而不是覆盖
ToolFallback
；按名称注册的工具UI优先级高于插槽。

Restyle

重新样式化

Thread
sets 
--thread-max-width
, 
--composer-bg
, 
--composer-radius
, and 
--composer-padding
inline on 
ThreadPrimitive.Root
, so change them by editing your copy of 
thread.aui.tsx
, not from an outer class. Everything else is Tailwind on the copied file.
Thread
会在
ThreadPrimitive.Root
上内联设置
--thread-max-width
、
--composer-bg
、
--composer-radius
和
--composer-padding
，因此请通过编辑你所复制的
thread.aui.tsx
文件来修改这些值，而不是通过外部类。其他所有样式都在复制后的文件中使用Tailwind实现。

Use a standalone element

使用独立型元素

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

<AgentPlan
  steps={["Read the schema", "Write the migration", "Run the tests"]}
  activeIndex={1}
/>;
Standalone elements take plain props (here 
steps: readonly string[]
and 
activeIndex: number
, plus any 
div
props) and never read runtime state, so they work in a tool 
render
, in a dashboard, or in Storybook. Each catalog page's "Standalone" tab shows the exact prop shape; the standalone reference summarizes the ones you will reach for most.
tsx
import { AgentPlan } from "@/components/assistant-ui/elements/agent-plan";

<AgentPlan
  steps={["Read the schema", "Write the migration", "Run the tests"]}
  activeIndex={1}
/>;
独立型元素接受普通props（此处为
steps: readonly string[]
和
activeIndex: number
，以及任何
div
的props），并且从不读取运行时状态，因此它们可以在工具的
render
方法、仪表板或Storybook中使用。每个组件库页面的“Standalone”标签页显示了确切的props结构；独立元素参考文档总结了你最常用的那些props。

Shared surface tokens

共享界面令牌

elements-surfaces
installs 
components/assistant-ui/elements/surfaces.tsx
, a set of class-string constants and two helpers that give every element the same look: 
paper
and 
floating
(card and popover fills), 
field
and 
fieldInteractive
(inputs), 
pressable
, 
ghostButton
, 
inkButton
, 
mono
, 
live
(the streaming accent), 
iconSwap
and 
labelSwap
transitions, 
collapsePanel
, 
codeScroll
and 
codeSurface
, plus 
ShimmerLabel
and 
SwapLabel
. Reuse them in your own components with 
cn(...)
from 
@/lib/utils
(the CLI scaffolds 
lib/utils.ts
if it is missing) so custom UI matches the catalog.
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与组件库的样式保持一致。

Common Gotchas

常见问题

Cannot find module '@/components/assistant-ui/thread'
  • Elements moved under 
    elements/
    and runtime-connected files carry the 
    .aui
    suffix: 
    @/components/assistant-ui/elements/thread.aui
    . Renderers and standalone elements have no suffix.
Element renders but looks unstyled
  • The registry assumes Tailwind v4 and the shadcn theme variables in 
    globals.css
    (
    @import "tailwindcss"
    plus the 
    --background
    , 
    --foreground
    , 
    --border
    family). 
    npx assistant-ui@latest init
    writes them; in a hand-rolled project copy them from a 
    create
    scaffold.
CLI installed the wrong flavor
  • add
    reads the 
    style
    field of 
    components.json
    ; 
    base-*
    styles get Base UI, anything else gets Radix. Fix the style, then re-add with 
    --overwrite
    .
Thread re-renders every message on each parent render
  • The 
    components
    prop object was created inline. Hoist it to module scope or 
    useMemo
    .
A 
.aui
element throws about a missing provider
  • It must be a descendant of 
    AssistantRuntimeProvider
    (or an 
    AuiProvider
    whose config supplies the scope it reads). Standalone elements have no such requirement.
Registry item not found
  • Runtime-connected and renderer items use the short name (
    thread
    , 
    markdown-text
    ); standalone items are prefixed (
    elements-agent-plan
    ). The catalog lists the exact item per element.
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风格。修改style字段后，使用
    --overwrite
    参数重新添加。
Thread在父组件每次渲染时都会重新渲染所有消息
  • components
    属性对象是在内部创建的。请将其提升到模块作用域或使用
    useMemo
    缓存。
.aui
元素抛出缺少Provider的错误
  • 它必须是
    AssistantRuntimeProvider
    （或提供其读取范围的
    AuiProvider
    ）的后代元素。独立型元素没有此要求。
未找到注册表项
  • 连接运行时的元素和渲染器使用短名称（
    thread
    、
    markdown-text
    ）；独立型元素带有前缀（
    elements-agent-plan
    ）。组件库目录列出了每个元素对应的准确注册表项。

Related Skills

相关技能

  • primitives -- the unstyled building blocks the 
    .aui
    elements compose
  • setup -- 
    create
    , 
    init
    , and the rest of the CLI
  • tools -- toolkit 
    render
    entries that replace 
    ToolFallback
    per tool
  • generative-ui -- the 
    generative-ui
    renderer and the component vocabulary
  • markdown -- 
    markdown-text
    , 
    shiki-highlighter
    , 
    syntax-highlighter
    , 
    mermaid-diagram
  • thread-list -- 
    thread-list
    , 
    threadlist-sidebar
    , 
    thread-search
    , 
    conversation-map
  • 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