Chat Launcher

PersonaChatLauncher is a floating action button (FAB) that toggles a PersonaChatView panel — for mounting a chat widget on any page as a support-style bubble, rather than dedicating a full-page route to chat.

import { PersonaChatLauncher } from '@personaai/ui';

Basic usage

<PersonaChatLauncher
  agentId="my-agent-id"
  position="bottom-right"
  greeting="Hi! How can I help?"
  title="Support"
/>

Renders a 56px round button in the bottom-right corner. Clicking it opens a floating panel containing a full PersonaChatView. Clicking again (or the X button) closes it.

Panel dimensions

The panel is a fixed-size floating container. Control its size with panelWidth and panelHeight:

<PersonaChatLauncher
  agentId="my-agent-id"
  panelWidth="28rem"    // default: 24rem (384px)
  panelHeight="32rem"   // default: 36rem (576px)
/>

The panel has max-h-[calc(100vh-7rem)] and max-w-[calc(100vw-2rem)] constraints — it never overflows the viewport, even if you set very large dimensions.

Position

// Bottom-right (default)
<PersonaChatLauncher position="bottom-right" />

// Bottom-left
<PersonaChatLauncher position="bottom-left" />

Both the FAB and the panel respect the position — right-6 / left-6 for the FAB, right-6 / left-6 for the panel.

Controlled vs. uncontrolled open state

Uncontrolled (default): The launcher manages its own open/closed state internally.

<PersonaChatLauncher defaultOpen={true} />  // starts open

Controlled: You manage the state externally.

function App() {
  const [chatOpen, setChatOpen] = useState(false);

  return (
    <>
      <button onClick={() => setChatOpen(true)}>Open Support</button>
      <PersonaChatLauncher
        open={chatOpen}
        onOpenChange={setChatOpen}
        agentId="my-agent-id"
      />
    </>
  );
}

When open is provided, onOpenChange is called on every toggle, and the internal state is bypassed.

Custom FAB icon

Replace the default MessageCircle icon with your own:

<PersonaChatLauncher
  fabIcon={<HelpCircle className="size-6" />}
  agentId="my-agent-id"
/>

The icon renders inside the FAB button (56px round, themed with --persona-primary).

Container-query responsive behavior

This is the most important technical detail about the launcher. Inside the floating panel:

PersonaSidebar needs to decide whether to dock inline or overlay as a full-screen panel.
PersonaFilesDrawer needs the same decision.

Normally these components use Tailwind’s md: / lg: responsive prefixes, which key off the browser viewport. But inside the launcher’s floating panel (24rem wide on a 1440px desktop), the viewport is still desktop-width even though the panel is narrow — so the sidebar/drawer would wrongly dock inline and compress the message area into a sliver. Since v0.7.3, PersonaChatView’s root is a named CSS container (@container/persona-chat), and both PersonaSidebar and PersonaFilesDrawer key their breakpoints off container queries:

/* Sidebar: overlay below 768px container-width, dock above */
@container persona-chat (max-width: 767px) { /* full-screen overlay */ }
@container persona-chat (min-width: 768px)  { /* docked inline */ }

/* Drawer: overlay below 1024px container-width, dock above */
@container persona-chat (max-width: 1023px) { /* full-screen overlay */ }
@container persona-chat (min-width: 1024px)  { /* docked inline */ }

This means:

On a narrow phone (375px viewport): the panel is also narrow → container is narrow → sidebar/drawer overlay correctly.
On a wide desktop (1440px viewport) with the launcher’s 24rem panel: the panel is still 384px → container is narrow → sidebar/drawer overlay correctly.
On a full-page PersonaChatView (1200px wide): the container is wide → sidebar/drawer dock inline correctly.

One rule covers all cases, no configuration needed.

Theme propagation

The FAB button is a sibling of PersonaChatView’s subtree, not a descendant. CSS custom properties set on PersonaChatView’s root don’t reach the FAB. The launcher handles this by computing buildThemeStyles(theme) once and applying it to a common ancestor (<div style={themeStyles} className="contents">) that wraps both the FAB and the panel. The className="contents" makes this wrapper invisible to layout — it contributes no box, just provides the CSS variable scope. PersonaChatView also sets the same styles on its own root (harmless duplication), but the launcher’s wrapper ensures primaryColor correctly colors the FAB button.

Props reference

Launcher-specific props

Prop	Type	Default	Description
`position`	`'bottom-right' \| 'bottom-left'`	`'bottom-right'`	Corner for FAB and panel.
`defaultOpen`	`boolean`	`false`	Initial open state (uncontrolled).
`open`	`boolean`	—	Controlled open state.
`onOpenChange`	`(open: boolean) => void`	—	Open state change callback.
`fabIcon`	`ReactNode`	`MessageCircle`	Custom FAB icon.
`panelWidth`	`string`	`'24rem'`	Panel CSS width.
`panelHeight`	`string`	`'36rem'`	Panel CSS height.
`fabClassName`	`string`	—	Extra class on FAB button.
`panelClassName`	`string`	—	Extra class on floating panel.

Passed-through PersonaChatViewProps

Everything else is passed straight through to the internal PersonaChatView:

Prop	Type	Description
`agentId`	`string`	Agent to chat with.
`threadId`	`string`	Controlled thread.
`onThreadChange`	`(id) => void`	Thread change callback.
`greeting`	`string`	Empty-state greeting.
`title`	`string`	Toolbar title.
`starterPrompts`	`StarterPromptItem[]`	Quick-action buttons.
`toolRenderers`	`ToolRendererMap`	Custom tool card renderers.
`classNames`	`ClassNamesOverride`	Internal element class overrides.
`theme`	`PersonaCustomTheme`	Color theme.
`showSidebar`	`boolean`	Sidebar visibility.
`showFilesDrawer`	`boolean`	Files drawer visibility.
`showUserAvatar`	`boolean`	User avatar visibility.
`showAssistantAvatar`	`boolean`	Assistant avatar visibility.
`userAvatar`	`ReactNode`	Custom user avatar.
`assistantAvatar`	`ReactNode`	Custom assistant avatar.
`groupTools`	`boolean`	Tool call grouping.
`toolClusterLabels`	`PersonaToolClusterLabels`	Cluster title overrides.

Layout structure

<div style={themeStyles} className="contents">       ← common ancestor for theme vars
  {isOpen && (
    <div className="fixed bottom-24 right-6 ...">    ← floating panel
      <PersonaChatView {...props} />
    </div>
  )}
  <button className="fixed bottom-6 right-6 ...">    ← FAB button
    {fabIcon ?? <MessageCircle />}
  </button>
</div>

Accessibility

FAB has aria-label="Open chat" / aria-label="Close chat" toggled by state.
Panel content is a full PersonaChatView with standard keyboard navigation (Enter to send, Shift+Enter for newline, Escape to stop streaming).

Integration examples

With Next.js App Router

// app/layout.tsx
import { PersonaLauncher } from '@/components/PersonaLauncher';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <PersonaLauncher />
      </body>
    </html>
  );
}

// components/PersonaLauncher.tsx
'use client';
import { PersonaProvider } from '@personaai/react';
import { PersonaChatLauncher } from '@personaai/ui';
import '@personaai/ui/styles.css';

export function PersonaLauncher() {
  return (
    <PersonaProvider
      baseUrl={process.env.NEXT_PUBLIC_PERSONA_URL!}
      getAuthToken={async () => {
        const res = await fetch('/api/auth/token');
        return (await res.json()).token;
      }}
      defaultAgentId={process.env.NEXT_PUBLIC_DEFAULT_AGENT_ID}
    >
      <PersonaChatLauncher
        agentId={process.env.NEXT_PUBLIC_DEFAULT_AGENT_ID}
        position="bottom-right"
        title="Support"
        greeting="How can we help?"
      />
    </PersonaProvider>
  );
}

With a help desk ticketing system

function HelpDesk() {
  const [ticketContext, setTicketContext] = useState(null);

  return (
    <PersonaProvider baseUrl="..." getAuthToken={...}>
      <PersonaChatLauncher
        agentId="help-desk-agent"
        greeting={`Hi! I see you're looking at ticket #${ticketContext?.id}. How can I help?`}
        starterPrompts={[
          { title: '📋 Summarize', prompt: `Summarize ticket ${ticketContext?.id}` },
          { title: '💬 Draft reply', prompt: `Draft a reply for this customer` },
        ]}
      />
    </PersonaProvider>
  );
}

Node.js SDK Reference

React SDK Reference

UI Components Reference

Next.js Adapter

Express Adapter

NestJS Adapter

Python SDK Reference

Runtime Reference

Basic usage

Panel dimensions

Position

Controlled vs. uncontrolled open state

Custom FAB icon

Container-query responsive behavior

Theme propagation

Props reference

Launcher-specific props

Passed-through PersonaChatViewProps

Layout structure

Accessibility

Integration examples

With Next.js App Router

With a help desk ticketing system

​Basic usage

​Panel dimensions

​Position

​Controlled vs. uncontrolled open state

​Custom FAB icon

​Container-query responsive behavior

​Theme propagation

​Props reference

​Launcher-specific props

​Passed-through PersonaChatViewProps

​Layout structure

​Accessibility

​Integration examples

​With Next.js App Router

​With a help desk ticketing system

Basic usage

Panel dimensions

Position

Controlled vs. uncontrolled open state

Custom FAB icon

Container-query responsive behavior

Theme propagation

Props reference

Launcher-specific props

Passed-through PersonaChatViewProps

Layout structure

Accessibility

Integration examples

With Next.js App Router

With a help desk ticketing system