ai-elements

AI Elements

AI Elementsは、AIを活用したユーザーインターフェースの構築に役立つ、包括的なReactコンポーネントライブラリです。チャットインターフェース、ツール実行の可視化、推論の表示、ワークフロー管理に特化した30種類以上のコンポーネントを提供します。

インストール

shadcnレジストリからインストールします。

npx shadcn@latest add https://ai-elements.vercel.app/r/[component-name]

インポートパターン：コンポーネントはバレルエクスポートではなく、個別のファイルからインポートします。

// Correct - import from specific files
import { Conversation } from "@/components/ai-elements/conversation";
import { Message } from "@/components/ai-elements/message";
import { PromptInput } from "@/components/ai-elements/prompt-input";

// Incorrect - no barrel export
import { Conversation, Message } from "@/components/ai-elements";

ゲート（例に依存する前に確認）

AI Elementsを追加または接続する際は、セットアップを前提とせず確認できるよう、次の手順に従ってください。

1. 各コンポーネントをインストールする — 必要なコンポーネントごとに、npx shadcn@latest add https://ai-elements.vercel.app/r/[component-name]を実行します。

   • **合格条件：**コマンドが正常に完了し、そのコンポーネントのファイルがプロジェクトのcomponents/ai-elements/（または、追加先としてcomponents.jsonで指定されているディレクトリ）に存在すること。

2. インポートパスを合わせる — すべてのimport … from "@/components/ai-elements/..."が、リポジトリの実際のエイリアスとフォルダー構成に一致している必要があります。

   • **合格条件：**各インポートがディスク上のファイルを参照していること（IDEでの移動、またはビルド／tscで、該当パスに対する「cannot find module」エラーが表示されないこと）。

3. Tool／Confirmationの状態をAI SDKに合わせる — 承認に関する状態を含む状態文字列は、インストールされているaiパッケージのメジャーバージョン／バージョンによって異なります。

   • 合格条件：ToolHeader、Tool、またはConfirmationに渡す状態が、記憶だけを頼りにコピーしたものではなく、インストール済みのAI SDKのバージョンで定義されていること（ドキュメントまたはエクスポートされた型で確認）。

コンポーネントのカテゴリ

会話コンポーネント

メッセージ、添付ファイル、自動スクロール機能を備えたチャット形式のインターフェースを表示するコンポーネントです。

• Conversation：自動スクロール機能を備えたコンテナー
• Message：ロールに応じたスタイルの個別メッセージ表示
• MessageAttachment：ファイルと画像の添付ファイル
• MessageBranch：別の応答への移動

詳しくは、references/conversation.mdを参照してください。

プロンプト入力コンポーネント

ファイル添付、ドラッグ＆ドロップ、音声入力、状態管理に対応した高度なテキスト入力です。

• PromptInput：ファイル処理機能を備えたフォームコンテナー
• PromptInputTextarea：入力に合わせて高さが変わるテキストエリア
• PromptInputSubmit：状態に応じて変化する送信ボタン
• PromptInputAttachments：ファイル添付の表示
• PromptInputProvider：グローバルな状態管理

詳しくは、references/prompt-input.mdを参照してください。

ワークフローコンポーネント

ジョブキュー、ツール実行、承認ワークフローを表示するコンポーネントです。

• Queue：ジョブキューのコンテナー
• QueueItem：状態を備えた個々のキュー項目
• Tool：折りたたみ可能な状態を備えたツール実行の表示
• Confirmation：承認ワークフローのコンポーネント
• Reasoning：折りたたみ可能な思考／推論の表示

詳しくは、references/workflow.mdを参照してください。

可視化コンポーネント

ワークフローの可視化とカスタムノードタイプに対応した、ReactFlowベースのコンポーネントです。

• Canvas：航空分野に特化したデフォルト設定を備えたReactFlowラッパー
• Node：ハンドルを備えたカスタムノードコンポーネント
• Edge：一時的なエッジとアニメーション付きのエッジタイプ
• Controls、Panel、Toolbar：ナビゲーションと制御用の要素

詳しくは、references/visualization.mdを参照してください。

shadcn/uiとの統合

AI Elementsはshadcn/uiを基盤として構築されており、そのテーマシステムとシームレスに統合されます。

• shadcn/uiのデザイントークン（色、間隔、タイポグラフィ）を使用
• CSS変数を介してライトモード／ダークモードに対応
• shadcn/uiのコンポーネント（Button、Card、Collapsibleなど）と互換性あり
• shadcn/uiのコンポーネント合成パターンに準拠

主な設計パターン

コンポーネント合成

AI Elementsは合成を優先するアプローチを採用しており、大きなコンポーネントを小さなプリミティブから構築します。

<Tool>
  <ToolHeader title="search" type="tool-call-search" state="output-available" />
  <ToolContent>
    <ToolInput input={{ query: "AI tools" }} />
    <ToolOutput output={results} errorText={undefined} />
  </ToolContent>
</Tool>

コンテキストベースの状態管理

多くのコンポーネントは、状態管理に React Context を使用します。

• グローバルな入力状態には PromptInputProvider
• 代替応答のナビゲーションには MessageBranch
• 承認ワークフローの状態には Confirmation
• 折りたたみ可能な思考状態には Reasoning

制御コンポーネントと非制御コンポーネント

コンポーネントは、制御パターンと非制御パターンの両方に対応しています。

// Uncontrolled (self-managed state)
<PromptInput onSubmit={handleSubmit} />

// Controlled (external state)
<PromptInputProvider initialInput="">
  <PromptInput onSubmit={handleSubmit} />
</PromptInputProvider>

ツールの状態マシン

Tool コンポーネントは、Vercel AI SDK の状態マシンに従います。

1. input-streaming：パラメーターを受信中
2. input-available：実行可能
3. approval-requested：ユーザーの承認待ち（SDK v6）
4. approval-responded：ユーザーが応答済み（SDK v6）
5. output-available：実行完了
6. output-error：実行失敗
7. output-denied：承認が拒否されました

キューパターン

キューコンポーネントは、階層構造での整理に対応しています。

<Queue>
  <QueueSection defaultOpen={true}>
    <QueueSectionTrigger>
      <QueueSectionLabel count={3} label="tasks" icon={<Icon />} />
    </QueueSectionTrigger>
    <QueueSectionContent>
      <QueueList>
        <QueueItem>
          <QueueItemIndicator completed={false} />
          <QueueItemContent>Task description</QueueItemContent>
        </QueueItem>
      </QueueList>
    </QueueSectionContent>
  </QueueSection>
</Queue>

自動スクロールの動作

Conversation コンポーネントは、インテリジェントな自動スクロールに use-stick-to-bottom フックを使用します。

• 新しいメッセージが届くと、自動的に一番下までスクロールします
• ユーザーが上方向にスクロールすると、自動スクロールを一時停止します
• 一番下にいないときは、一番下までスクロールするボタンを表示します
• スムーズスクロールと即時スクロールのモードに対応しています

ファイル添付の処理

PromptInput は、包括的なファイル処理機能を提供します。

• ドラッグ＆ドロップに対応（ローカルまたはグローバル）
• 画像やファイルの貼り付けに対応
• ファイル形式の検証（accept プロパティ）
• ファイルサイズの上限（maxFileSize プロパティ）
• ファイル数の上限（maxFiles プロパティ）
• 画像のプレビューとファイルのアイコン表示
• 送信時に blob URL から data URL へ自動変換

音声入力

PromptInputSpeechButton は、音声入力に Web Speech API を使用します。

• ブラウザー上で音声を認識
• 連続認識モード
• 中間結果に対応
• テキストエリアにテキストを自動挿入
• 録音中の視覚的なフィードバック

Reasoning の自動折りたたみ

Reasoning コンポーネントは、自動折りたたみの動作を提供します。

• ストリーミング開始時に自動で開きます
• ストリーミング終了から 1 秒後に閉じます
• 思考時間を秒単位で記録します
• ストリーミング中は、きらめき効果とともに「思考中…」と表示します
• 完了時は「N 秒間思考しました」と表示します

TypeScript の型

すべてのコンポーネントは TypeScript で完全に型付けされています。

import type { ToolUIPart, FileUIPart, UIMessage } from "ai";

type ToolProps = ComponentProps<typeof Collapsible>;
type QueueItemProps = ComponentProps<"li">;
type MessageAttachmentProps = HTMLAttributes<HTMLDivElement> & {
  data: FileUIPart;
  onRemove?: () => void;
};

よくある使用例

チャットインターフェース

Conversation、Message、PromptInput を組み合わせて、完全なチャット UI を作成します。

import { Conversation, ConversationContent, ConversationScrollButton } from "@/components/ai-elements/conversation";
import { Message, MessageContent, MessageResponse } from "@/components/ai-elements/message";
import {
  PromptInput,
  PromptInputTextarea,
  PromptInputFooter,
  PromptInputTools,
  PromptInputButton,
  PromptInputSubmit
} from "@/components/ai-elements/prompt-input";

<div className="flex flex-col h-screen">
  <Conversation>
    <ConversationContent>
      {messages.map(msg => (
        <Message key={msg.id} from={msg.role}>
          <MessageContent>
            <MessageResponse>{msg.content}</MessageResponse>
          </MessageContent>
        </Message>
      ))}
    </ConversationContent>
    <ConversationScrollButton />
  </Conversation>

  <PromptInput onSubmit={handleSubmit}>
    <PromptInputTextarea />
    <PromptInputFooter>
      <PromptInputTools>
        <PromptInputButton onClick={() => attachments.openFileDialog()}>
          <PaperclipIcon />
        </PromptInputButton>
      </PromptInputTools>
      <PromptInputSubmit status={chatStatus} />
    </PromptInputFooter>
  </PromptInput>
</div>

ツール実行の表示

ツールの実行内容を詳細情報とともに展開して表示します。

import { Tool, ToolHeader, ToolContent, ToolInput, ToolOutput } from "@/components/ai-elements/tool";

{toolInvocations.map(tool => (
  <Tool key={tool.id}>
    <ToolHeader
      title={tool.toolName}
      type={`tool-call-${tool.toolName}`}
      state={tool.state}
    />
    <ToolContent>
      <ToolInput input={tool.args} />
      {tool.result && (
        <ToolOutput output={tool.result} errorText={tool.error} />
      )}
    </ToolContent>
  </Tool>
))}

承認ワークフロー

アクションを実行する前に、ユーザーに確認を求めます。

import {
  Confirmation,
  ConfirmationTitle,
  ConfirmationRequest,
  ConfirmationActions,
  ConfirmationAction,
  ConfirmationAccepted,
  ConfirmationRejected
} from "@/components/ai-elements/confirmation";

<Confirmation approval={tool.approval} state={tool.state}>
  <ConfirmationTitle>
    Approve deletion of {resource}?
  </ConfirmationTitle>

  <ConfirmationRequest>
    <ConfirmationActions>
      <ConfirmationAction onClick={approve} variant="default">
        Approve
      </ConfirmationAction>
      <ConfirmationAction onClick={reject} variant="outline">
        Reject
      </ConfirmationAction>
    </ConfirmationActions>
  </ConfirmationRequest>

  <ConfirmationAccepted>
    Action approved and executed.
  </ConfirmationAccepted>

  <ConfirmationRejected>
    Action rejected.
  </ConfirmationRejected>
</Confirmation>

ジョブキューの管理

完了状況とともにタスクリストを表示します。

import {
  Queue,
  QueueSection,
  QueueSectionTrigger,
  QueueSectionLabel,
  QueueSectionContent,
  QueueList,
  QueueItem,
  QueueItemIndicator,
  QueueItemContent,
  QueueItemDescription
} from "@/components/ai-elements/queue";

<Queue>
  <QueueSection>
    <QueueSectionTrigger>
      <QueueSectionLabel count={todos.length} label="todos" />
    </QueueSectionTrigger>
    <QueueSectionContent>
      <QueueList>
        {todos.map(todo => (
          <QueueItem key={todo.id}>
            <QueueItemIndicator completed={todo.status === 'completed'} />
            <QueueItemContent completed={todo.status === 'completed'}>
              {todo.title}
            </QueueItemContent>
            {todo.description && (
              <QueueItemDescription completed={todo.status === 'completed'}>
                {todo.description}
              </QueueItemDescription>
            )}
          </QueueItem>
        ))}
      </QueueList>
    </QueueSectionContent>
  </QueueSection>
</Queue>

アクセシビリティ

コンポーネントには、次のアクセシビリティ機能が含まれています。

• ARIA ラベルとロール
• キーボードナビゲーションへの対応
• スクリーンリーダーへの通知
• フォーカス管理
• セマンティック HTML 要素

アニメーション

多くのコンポーネントは、滑らかなアニメーションに Framer Motion を使用します。

• 読み込み状態のきらめき効果
• 折りたたみ可能なコンテンツのトランジション
• Canvas の端のアニメーション
• ローダースピナーの回転

参考資料

• Conversation コンポーネント
• Prompt Input コンポーネント
• ワークフローコンポーネント
• 可視化コンポーネント