AssistantModalPrimitive

Floating assistant modal primitives for building support chat, copilot, and embedded assistant experiences.

For examples and usage patterns, see AssistantModal.

Anatomy

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

const AssistantModal = () => (
  <AssistantModalPrimitive.Root>
    <AssistantModalPrimitive.Trigger>
      <FloatingAssistantButton />
    </AssistantModalPrimitive.Trigger>
    <AssistantModalPrimitive.Content>
      <Thread />
    </AssistantModalPrimitive.Content>
  </AssistantModalPrimitive.Root>
);

API Reference

Root

AssistantModalPrimitiveRootProps

open?boolean
defaultOpen?boolean
onOpenChange?(open: boolean) => void
modal?boolean
unstable_openOnRunStart?boolean | undefinedunstable

Trigger

This primitive renders a <button> element unless asChild is set.

AssistantModalPrimitiveTriggerProps

asChildboolean= false: Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.
render?ReactElement | undefined

Data attribute	Values
`[data-state]`	`"open" \| "closed"`

Content

This primitive renders a <div> element unless asChild is set.

AssistantModalPrimitiveContentProps

asChildboolean= false

Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.

onOpenAutoFocus?FocusScopeProps['onMountAutoFocus']

Event handler called when auto-focusing on open. Can be prevented.

side?Side

sideOffset?number

align?Align

alignOffset?number

arrowPadding?number

avoidCollisions?boolean

collisionBoundary?Boundary | Boundary[]

collisionPadding?number | Partial<Record<Side, number>>

sticky?'partial' | 'always'

hideWhenDetached?boolean

updatePositionStrategy?'optimized' | 'always'

onCloseAutoFocus?FocusScopeProps['onUnmountAutoFocus']

Event handler called when auto-focusing on close. Can be prevented.

onEscapeKeyDown?(event: KeyboardEvent) => void

Event handler called when the escape key is down. Can be prevented.

onPointerDownOutside?(event: PointerDownOutsideEvent) => void

Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.

onFocusOutside?(event: FocusOutsideEvent) => void

Event handler called when the focus moves outside of the `DismissableLayer`. Can be prevented.

onInteractOutside?(event: PointerDownOutsideEvent | FocusOutsideEvent) => void

Event handler called when an interaction happens outside the `DismissableLayer`. Specifically, when a `pointerdown` event happens outside or focus moves outside of it. Can be prevented.

forceMount?true

Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

deferPointerDownOutside?boolean

When `true`, a `'pointerdown'` event outside of the layered element will wait for the interaction's click event before dispatching, allowing third-party code to stop propagation of later events and cancel dismissal.

render?ReactElement | undefined

portalProps?ComponentPropsWithoutRef<typeof PopoverPrimitive.Portal> | undefined

AssistantModalPrimitiveContentProps["portalProps"]

container?PortalProps['container']: Specify a container element to portal the content into.
forceMount?true: Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

dissmissOnInteractOutside?boolean | undefined

Anchor

This primitive renders a <div> element unless asChild is set.

AssistantModalPrimitiveAnchorProps

asChildboolean= false: Change the default rendered element for the one passed as a child, merging their props and behavior.

Read the Composition guide for more details.
virtualRef?React.RefObject<Measurable | null>
render?ReactElement | undefined