AssistantModal プリミティブは Radix Popover 上に構築されたフローティング・チャット・ポップオーバーです。チャットパネルを開く、固定位置のトリガーボタンを備えています。

assistant-ui 入門 : プリミティブ – AssistantModal

作成 : Masashi Okumura (@classcat.com)
作成日時 : 04/04/2026
バージョン : assistant-ui@0.0.87

* 本記事は assistant-ui.com/docs の以下のページを参考にしています :

• Primitives – AssistantModal

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。

 

 

 

assistant-ui 入門 : プリミティブ – AssistantModal

チャットパネルを開く、固定位置のトリガーボタンを備えたフローティングチャットポップオーバー。

AssistantModal プリミティブは Radix Popover 上に構築されたフローティング・チャット・ポップオーバーです。トリガーボタンはチャットパネルを開きます、これは一般的なフローティングアシスタントランチャーのパターンです。開発者はトリガー、コンテンツ、位置、アニメーションを制御できます。

Preview

Code

import { AssistantModalPrimitive } from "@assistant-ui/react";

function MinimalAssistantModal() {
  return (
    <AssistantModalPrimitive.Root>
      <AssistantModalPrimitive.Anchor>
        <AssistantModalPrimitive.Trigger>
          Open Chat
        </AssistantModalPrimitive.Trigger>
      </AssistantModalPrimitive.Anchor>
      <AssistantModalPrimitive.Content>
        {/* Your Thread goes here */}
      </AssistantModalPrimitive.Content>
    </AssistantModalPrimitive.Root>
  );
}

 

クイックスタート

最小限の例 :

import { AssistantModalPrimitive } from "@assistant-ui/react";

<AssistantModalPrimitive.Root>
  <AssistantModalPrimitive.Anchor>
    <AssistantModalPrimitive.Trigger>Open
  </AssistantModalPrimitive.Anchor>
  <AssistantModalPrimitive.Content>
    <Thread />
  </AssistantModalPrimitive.Content>
</AssistantModalPrimitive.Root>

Root はRadix Popover プロバイダー (DOM なし) で、Trigger は <button> をレンダリングし、Anchor は <div> をレンダリングし、Content はポータル内で <div> をレンダリングします。独自のクラス、アニメーション、レイアウトを追加できます。

ℹ️ ランタイム・セットアップ: プリミティブはランタイム・コンテキストを必要とします。UI をランタイム (例えば useLocalRuntime(…)) を持つ AssistantRuntimeProvider でラップします。See Pick a Runtime.

 

基本概念

ポップオーバー・アーキテクチャ

AssistantModal は Radix Popover 上に直接構築されています。

Root は状態の open/close を管理し、Trigger はそれを切り替え、Anchor はポップオーバーの位置を決定し、Content はフローティングパネルです。Radix Popover のすべての props は対応するパーツで利用可能です。

 

Anchor vs Trigger

Content は Tigger ではなく、Anchor を基準に位置決めされます。一般的なパターンは Trigger を Anchor 内でラップすることで、ポップオーバーがボタン自体ではなく (固定位置のボタンコンテナのような) より大きな領域に揃うようにします :

<AssistantModalPrimitive.Anchor className="fixed right-4 bottom-4 size-11">
  <AssistantModalPrimitive.Trigger>
    Open
  </AssistantModalPrimitive.Trigger>
</AssistantModalPrimitive.Anchor>

 

実行開始時の自動オープン

unstable_openOnRunStart prop (default true) は、アシスタントがレスポンスを開始した際に、自動的にモーダルをオープンします。つまり、モーダルが閉じている間にユーザがプログラムで実行を開始した場合、ポップアップ表示されてレスポンスを表示します。Set to false to disable.

 

閉じるときの挙動

Content は dissmissOnInteractOutside (現行APIの綴りに合わせ、意図的に “s” を一つ多くしています) を使用し、デフォルトは false です。モーダル (ウィンドウ) の外側をクリックしても閉じません。これは、ユーザがチャットを開いたままでページを操作するような、想定されるチャット UX とマッチしています。Set it to true for standard popover dismiss behavior.

 

パーツ (部品)

Root

Radix Popover プロバイダー、open/close 状態を管理します。DOM 要素はレンダリングされません。

<AssistantModalPrimitive.Root unstable_openOnRunStart={false}>
  ...
</AssistantModalPrimitive.Root>

 

Trigger

モーダルのオープンとクローズを切り替えるボタンです。asChild が設定されていない限り、<button> 要素をレンダリングします。

<AssistantModalPrimitive.Trigger className="rounded-full bg-primary px-4 py-2 text-primary-foreground">
  Open Chat
</AssistantModalPrimitive.Trigger>

 

Anchor

トリガーとコンテンツを共有アンカーを基準として配置します。asChild が設定されていない限り、<div> 要素をレンダリングします。

<AssistantModalPrimitive.Anchor className="fixed right-4 bottom-4">
  <AssistantModalPrimitive.Trigger>Chat</AssistantModalPrimitive.Trigger>
</AssistantModalPrimitive.Anchor>

 

Content

フローティング・チャットパネル。ポータル内に <div> 要素をレンダリングします。

<AssistantModalPrimitive.Content
  sideOffset={16}
  className="h-[600px] w-[400px] rounded-xl border bg-background shadow-lg"
>
  <Thread />
</AssistantModalPrimitive.Content>

以上