elements

assistant-ui Elements

最新の API については、常に assistant-ui.com/llms.txt を参照してください。

Elements は、スタイルなしのプリミティブの上に位置する、スタイル付きでプロジェクトにコピーして使うコンポーネントです。すべての element は CLI が components/assistant-ui/elements/ にコピーする TSX ファイルであるため、ソースを自分で所有し、その場でカスタマイズできます。assistant-ui.com/elements のカタログでは、各 element についてライブデモ、ランタイムレシピ、スタンドアロンレシピを記載しています。

リファレンス

• ./references/catalog.md -- セクションごとのすべての element と、そのレジストリアイテムおよびインストールされるファイル
• ./references/aui-elements.md -- ランタイムに接続された element（Thread、ThreadList、AssistantModal、AssistantSidebar、ToolFallback、ToolGroup、Reasoning、Sources、Attachment、ModelSelector、Voice、McpConfig、および各種レンダラー）
• ./references/standalone-elements.md -- セクションごとにグループ化された props 駆動の element と、重要な props の形状

2 種類の element

種類	ファイル	ランタイムが必要か	レジストリアイテム
ランタイム接続	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 element またはツールキットの render から使用されます	markdown-text、syntax-highlighter、shiki-highlighter、mermaid-diagram、generative-ui

いくつかの element は両方の形式で存在します。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 を選び、独自の state、ツールの結果、またはデザインモックからレンダリングする場合はスタンドアロンを選んでください。

インストール

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）を取得します。スタンドアロンの element は共有トークンのために elements-surfaces を取得します。

components.json がない場合、CLI は警告を出し、Base UI フレーバーをインストールします。shadcn CLI に element を直接解決させるには、スタイル対応 URL を登録します。

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

これで npx shadcn@latest add @assistant-ui/thread も機能します。base-* という名前のスタイルは Base UI フレーバーを受け取り、それ以外のすべてのスタイルは Radix を受け取ります。ほとんどの element は @assistant-ui/react のプリミティブのみを組み合わせ、両方に対して 1 つのソースを提供します。ライブラリ固有のサーフェスに触れるもの（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 のフォールバックとして残ります。

ランタイム接続の 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 は runtime prop を取らず、最も近いプロバイダーを読み取ります。ウェルカム画面、スレッド切り替え中の読み込み時に履歴スケルトン、メッセージリスト、最下部へスクロールするピル、フォローアップ候補、およびコンポーザーをレンダリングします。

ファイルをフォークする代わりにスロットをオーバーライドする

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。オブジェクトはモジュールスコープで定義するかメモ化してください。そうしないと、親がレンダリングするたびにメッセージのサブツリーが再マウントされます。ツールごとの UI には、ToolFallback をオーバーライドするのではなく、ツールキットのエントリに render を登録してください（tools を参照）。名前で登録されたツール UI はスロットより優先されます。

再スタイリング

Thread は --thread-max-width、--composer-bg、--composer-radius、--composer-padding を ThreadPrimitive.Root にインラインで設定するため、これらは外側のクラスからではなく、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}
/>;

スタンドアロン要素はプレーンな props（ここでは steps: readonly string[] と activeIndex: number、さらに任意の div props）を受け取り、ランタイムの状態を一切読み取らないため、ツールの render 内でも、ダッシュボード内でも、Storybook 内でも動作します。各カタログページの「Standalone」タブに正確な props の形が表示されます。standalone リファレンスには、最もよく使うものの概要がまとめられています。

共有サーフェストークン

elements-surfaces は components/assistant-ui/elements/surfaces.tsx をインストールします。これはクラス文字列の定数のセットと、すべての要素に同じ外観を与える 2 つのヘルパーです: paper と floating（カードとポップオーバーの塗り）、field と fieldInteractive（入力）、pressable、ghostButton、inkButton、mono、live（ストリーミングのアクセント）、iconSwap と labelSwap のトランジション、collapsePanel、codeScroll と codeSurface、さらに ShimmerLabel と SwapLabel。独自のコンポーネントで @/lib/utils の cn(...) を使って再利用してください（存在しない場合、CLI が lib/utils.ts を生成します）。そうすることでカスタム 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 prop オブジェクトがインラインで作成されています。モジュールスコープまたは useMemo に巻き上げてください。

.aui 要素がプロバイダの欠落について例外をスローする

• それは AssistantRuntimeProvider（または読み取るスコープを設定で提供する AuiProvider）の子孫でなければなりません。スタンドアロン要素にはそのような要件はありません。

レジストリアイテムが見つからない

• ランタイムに接続されるアイテムとレンダラーのアイテムは短い名前（thread、markdown-text）を使います。スタンドアロンのアイテムにはプレフィックスが付きます（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