OpenMax
Free Trial

Floating windows, dock and drawer

Open conversations outside the main page — draggable floating windows, a docked column on the right, a dock for minimized windows and a bottom drawer on small screens. With the SDK, mount ChatDockColumn and ChatFloatingSurfaces; to assemble your own, use the four surfaces in @openmaxai/chat/surfaces and the store that tracks open conversations.

Floating windows, dock and drawer

Users can open a conversation on any page and keep it open when they navigate. With the SDK you mount two components, both imported from @openmaxai/chat-sdk/react:

Component Where it goes What it shows
ChatDockColumn In your layout, as the sibling to the right of the main content Docked conversations: a tab strip on top, the current conversation below
ChatFloatingSurfaces Portals into the container you pass Floating conversation windows you can drag and resize, the dock of minimized windows, and the bottom drawer on small screens

Each window holds the conversation header (compact, with minimize and close at the far right) and the message area under the same host, reading and writing the same messages as the main page: a message sent from a floating window is already there when the main page opens that conversation, and new messages the main page receives show up in the window at the same time. You do not write the window contents.

When to use

  • Users chat while looking at another page, for example talking to an agent from its detail page.
  • You want conversations to follow the user: open windows stay open across navigation.
  • If you have a single chat page and never open conversations elsewhere, you do not need these components.

Examples

Mounting

Mount each component once in your app shell, inside ChatProvider. Their required props are container and isCompact. isCompact is a page-level layout choice: when it is true there is only the bottom drawer, and the floating windows, docked column and dock render nothing.

app-shell.tsx

import {
  ChatDockColumn,
  ChatFloatingSurfaces,
  ChatProvider,
  ChatRoot,
} from "@openmaxai/chat-sdk/react";

export function AppShell({ host, isCompact, children }: AppShellProps) {
  const container = typeof document === "undefined" ? null : document.body;
  return (
    <ChatProvider host={host}>
      <ChatRoot overlayContainer="body" style={{ display: "flex", height: "100dvh" }}>
        <main style={{ flex: 1, minWidth: 0 }}>{children}</main>
        <ChatDockColumn container={container} isCompact={isCompact} />
        <ChatFloatingSurfaces container={container} isCompact={isCompact} />
      </ChatRoot>
    </ChatProvider>
  );
}

ChatDockColumn must be a sibling of the main content: it takes up width and narrows the content instead of covering it. With no docked conversations it renders nothing and leaves no empty column.

Both go inside ChatRoot, which gives them their color scheme and landing node; ChatFloatingSurfaces wraps a scoped node into container and renders there, ChatDockColumn renders in place inside its own component root. Pass overlayContainer="body" as well, or overlays from the main area and cards dragged out of the dock can end up under the floating windows; the reasons are in Installation · Floating surfaces and overlayContainer. With ChatShadowRoot in place of ChatRoot it is the same: both components go among its children, and ChatFloatingSurfaces builds an island in container.

  • Both components must be inside ChatProvider; rendered outside it they throw.
  • Mount one ChatFloatingSurfaces and one ChatDockColumn per page: the store of open windows is one per page, and a second component of the same kind throws ChatSdkConfigError when it mounts. StrictMode's mount, unmount, mount again in development does not count as two.
  • Open windows (form, position, size, tab order) and the floating preferences live in the host's instanceScope.storage, keyed by instanceKey and the current user: with createChatHost({ storage: "localStorage" }) they survive a reload, and another user or another instanceKey does not see them. A window restored after a reload shows "loading" until its conversation is fetched; when the conversation is gone (removed from the group, group dissolved, no access) the window closes silently. Unread, @ and muted on the dock and docked tabs follow the host's conversation list live; you pass nothing.
  • Button labels (minimize, close, show more, the tab strip, the resize handle) come from the host's i18n capability; when your t does not know a key (it returns the key or an empty string) they fall back to useTranslation, which then needs an I18nextProvider above; see Internationalization.

Opening a conversation

Whether an open (host.openConversation, the composer controller, the profile card's "Send message", conversation links in messages, deep links) lands on the main page or in a window is decided by createChatHost's routeConversation: return "primary" to hand it to the main page, "detached" to open it in a window (floating or docked per the user's preference, a drawer on small screens; brought to front if already open), or "handled" when you handled it yourself (for example, navigating to the chat page). Without it: a mounted useChatSdkOpenConversation gets it, otherwise mounted surfaces do. With only ChatDockColumn mounted and no ChatFloatingSurfaces, conversations opened into the surfaces always land as docked tabs rather than following the preference (nothing would draw a floating window).

host.ts

import { createChatHost } from "@openmaxai/chat-sdk/react";

const host = createChatHost({
  adapter,
  routeConversation: () => (location.pathname === "/chat" ? "primary" : "detached"),
});

One host can be mounted in several ChatProviders side by side (for example, one around the chat page and one around the surfaces); host-level work (loading the current user, the realtime connection, the conversation list, the built-in image viewer) still happens once.

Floating windows only, no docking

Pass docking={false} to ChatFloatingSurfaces and do not mount ChatDockColumn. Every entry point that would produce a docked tab opens a floating window instead: dropping on the right edge leaves the window where you let go, the "open docked by default" preference has no effect, and conversations docked before a reload come back as floating windows. Records turned into floating windows are written back to storage, so switching back to true does not dock them again. If docking={false} and ChatDockColumn are on the same page, whichever mounts second throws ChatSdkConfigError. If you keep the default docking without mounting ChatDockColumn, a window that docks is drawn by nothing; in development builds the first one prints a console.warn that points you here.

app-shell.tsx

<ChatFloatingSurfaces container={container} isCompact={isCompact} docking={false} />

Minimizing into your own entry point

With minimizedDock={false} the SDK does not mount its minimized dock and you draw the entry point: read minimized windows with useChatSdkMinimizedSurfaces() and call its restore(id) on click. collapseAnchor returns your entry element; the minimize animation measures it when it starts and flies there, and fades out in place when it returns null or the element is not on the page.

minimized-chats.tsx

import { ChatFloatingSurfaces, useChatSdkMinimizedSurfaces } from "@openmaxai/chat-sdk/react";

// Minimized windows sit next to your own toolbar button. The button is always mounted, so even the first minimize has somewhere to fly to.
function MinimizedChats({ anchorRef }: { anchorRef: RefObject<HTMLButtonElement | null> }) {
  const { chats, restore } = useChatSdkMinimizedSurfaces();
  return (
    <div>
      <button ref={anchorRef} type="button">Chat</button>
      {chats.map((c) => (
        <button key={c.id} type="button" onClick={() => restore(c.id)}>
          {c.title}
        </button>
      ))}
    </div>
  );
}

// App shell: no ChatDockColumn
<ChatFloatingSurfaces
  container={container}
  isCompact={isCompact}
  docking={false}
  minimizedDock={false}
  collapseAnchor={() => anchorRef.current}
/>;

Read unread counts from useChatSdkConversationList rows by conversationId.

Assembling it yourself

Without the SDK, or when you want to decide what goes in a window, use the four surfaces in @openmaxai/chat/surfaces directly:

Component Where it goes What it shows
FloatingChatLayer Portals into the container you pass Floating conversation windows you can drag and resize
ChatDockColumn In your layout, as the sibling to the right of the main content Docked conversations: a tab strip on top, the current conversation below
ChatMinimizedDock Portals into container Minimized floating windows, as a row of avatars
ChatMobileDrawer Portals into container A bottom drawer on small screens, one conversation at a time

These draw only the frame, the tabs and the controls. The body of each window (message thread, composer and so on) comes from you through renderBody, built from the same components as the main page. Which conversations are open is kept in useFloatingChatStore, so a window can be opened from anywhere.

The examples in this section use components of @openmaxai/chat (the surfaces, MessageThread, ChatHeader), which have no style root: the SDK stylesheet applies only inside .omx-chat nodes, and they bring no such root of their own. So, as Mounting them yourself explains, render them inside ChatRoot and pass as container a node with the class omx-chat; the window body likewise needs an element of yours with the class omx-chat around it (plus omx-dark in dark mode), or styles of your own.

Mounting them yourself

Mount the four components once in your app shell, inside ChatProvider.

The SDK stylesheet applies only inside .omx-chat nodes. Render the four inside ChatRoot, and pass as container a node of yours with the class omx-chat (plus omx-dark in dark mode) rather than document.body itself, so the windows rendered there get the styles; this is what ChatFloatingSurfaces does for you.

app-shell.tsx

import { ChatProvider } from "@openmaxai/chat-sdk/react";
import {
  ChatDockColumn,
  ChatMinimizedDock,
  ChatMobileDrawer,
  FloatingChatLayer,
  installChatSurfaceStorage,
  type ChatSurfaceProps,
} from "@openmaxai/chat/surfaces";

installChatSurfaceStorage(window.localStorage);

export function AppShell({ host, isCompact, children }: AppShellProps) {
  const surface: ChatSurfaceProps = {
    isCompact,
    container: typeof document === "undefined" ? null : document.body,
    renderBody: (chat) => <ChatWindowBody chat={chat} />,
  };
  return (
    <ChatProvider host={host}>
      <div style={{ display: "flex", height: "100dvh" }}>
        <main style={{ flex: 1, minWidth: 0 }}>{children}</main>
        <ChatDockColumn {...surface} />
      </div>
      <FloatingChatLayer {...surface} />
      <ChatMinimizedDock isCompact={isCompact} container={surface.container} />
      <ChatMobileDrawer {...surface} />
    </ChatProvider>
  );
}

Inside ChatProvider the surfaces look up their button labels through the host's i18n capability first and fall back to useTranslation for keys it does not know; mounted outside ChatProvider they use only useTranslation, which needs an I18nextProvider above.

The window body

chat-window-body.tsx

import { ConversationScope } from "@openmaxai/chat-sdk/react";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { type FloatingChat, useFloatingChatStore } from "@openmaxai/chat/surfaces";

export function ChatWindowBody({ chat }: { chat: FloatingChat }) {
  const hydrate = useFloatingChatStore((s) => s.hydrate);
  const dropGone = useFloatingChatStore((s) => s.dropGone);

  // After a reload chat.conversation is empty: fetch it again.
  useEffect(() => {
    if (chat.conversation) return;
    fetchConversation(chat.conversationId).then((conversation) =>
      conversation ? hydrate(chat.id, conversation) : dropGone(chat.id),
    );
  }, [chat.id, chat.conversationId, chat.conversation, hydrate, dropGone]);

  return (
    <ConversationScope conversationId={chat.conversationId}>
      <MessageThread conversation={chat.conversation ?? null} composerChrome="flush" />
    </ConversationScope>
  );
}

fetchConversation is your own fetch function. Call dropGone only when the server says the conversation does not exist or the user has no access; it closes the window. On a network failure do not call it: the window stays and you fetch again later.

Opening a window yourself

import { useFloatingChatStore } from "@openmaxai/chat/surfaces";

useFloatingChatStore
  .getState()
  .open({ conversation, title: agentName, viewportWidth: window.innerWidth });

Each conversation has at most one window: opening the same conversation again brings its window to the front and un-minimizes it, or switches to its tab if it is docked. A new window opens floating or docked according to the preferences. title shows in the title bar and the dock, and is the placeholder until the conversation is loaded; with a title source installed (setTitleSource) the windows follow the source instead and fall back to title when it has no answer. viewportWidth is the current viewport width in px; the package does not read window itself, so pass it from the window the surfaces render in. Without it a new window is not kept inside the viewport (see Floating windows).

Your @openmaxai/chat must be the same version as @openmaxai/chat-sdk. With a different version there are two copies of the store: the window opens in yours, and the SDK's surfaces, which read the other one, never show it. See Installation.

Custom floating-window header

Without renderHeader, a floating window has its own title bar: the title plus minimize and close buttons. To use the same header as the chat page, pass renderHeader and use the chrome the shell gives you:

renderHeader: (chat, scope, chrome) =>
  chat.conversation ? (
    <ChatHeader
      /* …required props */
      conversation={chat.conversation}
      mode="compact"
      trailing={chrome.controls}
      overlayContainer={chrome.overlayContainer}
      rootProps={chrome.dragProps}
    />
  ) : (
    <div {...chrome.dragProps}>
      {chat.title}
      {chrome.controls}
    </div>
  ),

Render chrome.controls before the conversation is loaded too, or the window cannot be closed in the meantime.

  • chrome.controls are the minimize and close buttons. You must render them, or the window cannot be closed.
  • chrome.overlayContainer is the mount point a floating window passes, above all floating windows. The header's popovers must portal into it, or they appear behind the window.
  • Spread chrome.dragProps on the header's root element to make the whole header the drag handle.

renderHeader is used for floating windows only. Docked tabs carry their own avatar and title, and the drawer has its own title.

Behavior

Floating windows

  • A new window's outer frame is 480 × 640 px (title bar included) at (320, 96), and each additional one is offset 28 px down and to the right. When viewportWidth is given and the viewport is at least 768 px wide, the x position is limited to viewportWidth − w − 16 (w is the window width; x never goes below 0) so the whole window stays on screen; vertical offsets continue as usual. Below 768 px the surfaces show as a drawer and the position is not limited, so a window opened there does not keep a squeezed position after the viewport widens. With the "remember position" preference on, it uses the position and size of the window last moved or resized, unchanged.
  • Drag the title bar to move, drag any edge or corner to resize: the minimum width is 320 px (MIN_W, outer frame) and the minimum body height is 280 px (MIN_H), so the outer frame is at least 280 px plus the current title bar height. Clicking anywhere in a window brings it to the front.
  • Minimizing shrinks the window toward the bottom-right corner into the dock; clicking its avatar there restores its position and size.
  • Dragging a window to the right edge of the viewport and releasing it turns it into a tab in the docked column; with docking set to false it stays a floating window where you let go.

Docked column

  • A tab strip on top, the current tab's conversation below. Tabs are ordered by their latest new message, newest first; call noteActivity(conversationId, at) when a message arrives.
  • Tabs that do not fit in one row go under "Show more"; there is no scroll bar.
  • Closing the current tab switches to the tab on its left, or to the one on its right if it was leftmost; when no tab is left, the column goes away.
  • Dragging a tab out of the column and releasing it turns it back into a floating window, at the size it had before it was docked.
  • Drag the column's left edge to resize it: 400 px by default, between 320 and 720 px, and at most 60% of the viewport width; double-click the edge to reset. The width is kept in the dockWidth preference.

Bottom drawer

  • Shown only when isCompact is true, with the frontmost conversation only. Closing it (swipe down or tap the overlay) reveals the next one; the other conversations stay in the store.
  • The drawer is 80% of the viewport high. Opening it does not move the cursor into the composer, so the on-screen keyboard does not cover the messages.

API

SDK components

ChatDockColumn and ChatFloatingSurfaces are imported from @openmaxai/chat-sdk/react; see Mounting for where they go. ChatDockColumn takes ChatSdkSurfaceProps; ChatFloatingSurfaces takes ChatSdkFloatingSurfacesProps (the last three rows as well):

Prop Type Default Description
container HTMLElement | null required Where to portal, usually document.body; while it is null the floating windows, dock and drawer do not render (pass null during server rendering). ChatDockColumn does not portal; pass the same value
isCompact boolean required Small-screen layout. When true there is only the bottom drawer; floating windows, the dock and the docked column render nothing
renderThread (props: CwsMessageThreadProps) => ReactNode (props) => <CwsMessageThread {...props} /> Experimental. Renders the message thread in each window, docked tab and drawer, for example to wrap it in your providers or pass provisioningBlocked. Gets the props the SDK would pass (conversation is null while a restored window is loading) and must render exactly one CwsMessageThread with them. The header and window controls stay with the SDK
docking boolean true ChatFloatingSurfaces only. With false nothing docks; see Floating windows only, no docking
minimizedDock boolean true ChatFloatingSurfaces only. With false the minimized dock is not mounted; see Minimizing into your own entry point
collapseAnchor () => Element | null — ChatFloatingSurfaces only, called only when minimizedDock is false: once when the minimize animation starts, which flies to the center of the returned element; fades out in place when there is none

The window body, the window header and the store of open windows are handled by the SDK and not exported from it; read minimized windows through useChatSdkMinimizedSurfaces().

Components (when assembling it yourself)

All four components are imported from @openmaxai/chat/surfaces; see Mounting them yourself for where they go. Except ChatMinimizedDock, their props type is ChatSurfaceProps; props a component does not read are marked in its table.

FloatingChatLayer

The floating windows that are not minimized, portaled into container. Renders nothing when isCompact is true, container is null, or there are no floating windows.

Prop Type Default Description
isCompact boolean required Renders nothing when true
renderBody (chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode required The window body; scope is "floating-chat"
renderHeader (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode — Floating-window header; without it the built-in title bar (title plus minimize and close buttons) is used. See Custom floating-window header
renderPane (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode — Header and body together (same host); when given, renderHeader / renderBody are not called. presentation is "float"
container HTMLElement | null required Where to portal, usually document.body; renders nothing while it is null (pass null during server rendering)
collapseAnchor () => Element | null — Where the minimize animation flies; to the dock when not given. Called once when minimize is clicked; fades out in place when no usable element comes back

ChatDockColumn

The docked column. It renders in place in your page layout, not in a portal, as a sibling of the main content. Renders nothing when isCompact is true or nothing is docked; while a floating window is dragged to the right edge of the viewport, it first draws a drop band as wide as the column.

Prop Type Default Description
isCompact boolean required Renders nothing when true
renderBody (chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode required The body of the active tab; scope is "docked-chat"
renderHeader (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode — Not read. Docked tabs carry their own avatar and title
renderPane (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode — The current tab's header and body together, the header under the tab strip; presentation is "docked", no window controls. Without it only renderBody is called
container HTMLElement | null required Not read. Pass the same value as to the other three components
unreadCountOf (conversationId: string) => number — Unread count on each tab; see ChatSurfaceProps
unreadMentionOf (conversationId: string) => "direct" | "all" | null — @ badge at the bottom-left of each tab avatar; see ChatSurfaceProps
mutedOf (conversationId: string) => boolean — Greys out the unread count and the @everyone badge of muted conversations; see ChatSurfaceProps

ChatMinimizedDock

Minimized floating windows as a row of avatars, portaled into container. Renders nothing when isCompact is true, container is null, or nothing is minimized; moves aside when there is a docked column on the right.

Prop Type Default Description
isCompact boolean required Renders nothing when true
container HTMLElement | null required Where to portal; renders nothing while it is null
unreadCountOf (conversationId: string) => number — Unread count on each avatar; see ChatSurfaceProps
unreadMentionOf (conversationId: string) => "direct" | "all" | null — @ badge at the bottom-left of each avatar; see ChatSurfaceProps
mutedOf (conversationId: string) => boolean — Greys out the unread count and the @everyone badge of muted conversations; see ChatSurfaceProps

ChatMobileDrawer

The small-screen bottom drawer, showing the frontmost conversation, portaled into container. Renders nothing when isCompact is false, container is null, or no conversation is open.

Prop Type Default Description
isCompact boolean required Renders nothing when false
renderBody (chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode required The drawer body; scope is "floating-chat"
renderHeader (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode — Not read. The drawer's title is the conversation title
renderPane (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode — Header and body together; the header replaces the visible title (kept for screen readers); presentation is "drawer", the window control is a close button. Without it only renderBody is called
container HTMLElement | null required Where to portal; renders nothing while it is null

ChatSurfaceProps

The props type of FloatingChatLayer, ChatDockColumn and ChatMobileDrawer. Which fields each one reads is in its table above.

Prop Type Default Description
isCompact boolean required Small-screen layout. When true there is only the bottom drawer
renderBody (chat: FloatingChat, scope: ChatSurfaceScope) => ReactNode required The body of one conversation
renderHeader (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfaceHeaderChrome) => ReactNode — Floating-window header; without it the built-in title bar is used
renderPane (chat: FloatingChat, scope: ChatSurfaceScope, chrome: ChatSurfacePaneChrome) => ReactNode — Renders a conversation's header and body together, under the same host. Floating windows, the docked column and the drawer all call it; when given, renderHeader / renderBody are not called. The frame the shell passes is ChatSurfacePaneChrome
container HTMLElement | null required Where to portal, usually document.body; the components that portal render nothing while it is null
unreadCountOf (conversationId: string) => number — Unread count on docked tabs and in the dock, computed from your own unread source. Without it the value of conversation.unread_count at the moment the window opened is used (0 for observed conversations), and it never changes
unreadMentionOf (conversationId: string) => "direct" | "all" | null — The @ badge on docked tab and dock avatars: "direct" you were mentioned, "all" @everyone, null none. Both look the same and are read out differently. Without it the value of conversation.unread_mention at the moment the window opened is used (none for observed conversations), and it never changes
mutedOf (conversationId: string) => boolean — Whether the conversation is muted: the unread count and an "all" @ badge turn grey, a "direct" one stays red. Without it the value of conversation.muted at the moment the window opened is used (never muted for observed conversations)

ChatSurfaceScope is "floating-chat" | "docked-chat": which kind of surface the body is in (the drawer passes "floating-chat" too). It is for telling bodies apart and debugging, and changes no behavior.

ChatSurfaceHeaderChrome:

Field Type Description
controls ReactNode The minimize and close buttons; must be rendered
overlayContainer HTMLElement | null Mount point for the header's popovers. Floating windows pass one above all floating windows; the docked column and the drawer pass null, so popovers use the default (body)
dragProps { onPointerDown, className } Optional. Spread on the header's root element to make it the drag handle; floating windows only
frameClassName string Optional. Frame classes merged onto the header's root element; docked tabs and the drawer get a flat bar (bottom border only, no rounded corners)

ChatSurfacePaneChrome (the frame renderPane receives):

Field Type Description
presentation "float" | "docked" | "drawer" Whether this window is a floating window, a docked tab or the mobile drawer. A docked tab already shows the avatar and name, so the header need not
header ChatSurfaceHeaderChrome As above, for the header. controls depends on the presentation: minimize + close for floating windows, close for the drawer (swiping down still closes it), null for docked tabs; only floating windows have dragProps
bodyFrame (body: ReactNode) => ReactNode The body container (in a floating window it fills the height below the title bar, clips, passes composer-focus requests in). Wrap the body with it. The header and bodyFrame(...) must be direct children of the window root, or separated from it only by display: contents nodes; with an ordinary div wrapper the body grows with its content and overflows the window, without any error

FloatingChat

One window in the store:

Field Type Description
id string Window id, floating-chat-<conversationId>
conversationId string
conversation ChatConversation Optional. The conversation itself; not persisted, so empty after a reload until you call hydrate
title string Text in the title bar and the dock
x, y, w, h number Position and outer-frame size (px, relative to the viewport; h includes the title bar)
z number Stacking order; higher is on top
mode ChatSurfaceMode "list" | "float" | "docked"
minimized boolean Optional. Only meaningful for "float": the window is in the dock
dockOrder number Optional. Order of docking, used to sort tabs that have no message time
restore { x, y, w, h } Optional. Position and size before docking or minimizing
lastActivityAt string Optional. Time of the latest new message (ISO), written by noteActivity

useFloatingChatStore

A zustand store. Subscribe in components with useFloatingChatStore((s) => s.chats); outside components use useFloatingChatStore.getState().

Member Description
chats FloatingChat[], every open conversation
dockActiveId Window id of the docked column's current tab; null when nothing is docked
open({ conversation, title?, viewportWidth? }) Open a conversation; if it is already open, bring it to the front. title defaults to the conversation's name. viewportWidth (px) keeps a new window inside the viewport
close(id) Close a window
focus(id), move(id, x, y), resize(id, w, h) Bring to front, move, resize (w, h are the outer frame; values below MIN_W, MIN_H are clamped to them, against the outer frame since the store does not know the title bar height)
dock(id), undock(id, x, y) Dock into the right-hand column; drag out of the column to a point, restoring the size from before docking
minimize(id), restoreFromDock(id) Put into the dock; restore from the dock. Docked tabs cannot be minimized
setDockActive(id) Switch the docked column's current tab
hydrate(id, conversation) Put a fetched conversation back after a reload
dropGone(id) Close the window when the server says the conversation does not exist or the user has no access
clearDetached() Close every window (floating, docked, dock, drawer); the main chat is not affected. Use it on org switch and logout
setTitleSource(source) Install where window titles come from (ChatSurfaceTitleSource); returns the function that uninstalls it. Throws while another source is installed. With a source, the stored title is only the placeholder shown until it answers, and again whenever it has none; the source's answer is never written back. @experimental
noteActivity(conversationId, at) The conversation has a new message (at is an ISO time). Only moves forward; does nothing when the conversation has no window
composerFocus The pending composer-focus request { chatId, seq }; null or absent when there is none. Not persisted
requestComposerFocus(id), settleComposerFocus(seq) Ask for the cursor to go into this window's composer; clear the request once the body has handled it. The surfaces call these themselves; you normally do not

Preferences

useChatPreferencesStore, persisted together with the windows:

Field Type Default Description
defaultSurface ChatSurfacePreference ("float" | "docked") "float" Whether open opens a new conversation floating or docked
rememberGeometry boolean true New windows use the last position and size. When off, it is still recorded, just not used for new windows
lastGeometry RememberedGeometry | null null The last { x, y, w, h } (w, h are the outer frame)
dockWidth number | null null Docked column width the user dragged to; null means the default 400 px
infoSidebarOpen boolean false Whether the conversation info sidebar is open beside the main conversation (wide layouts; one value for the device, not per conversation)
infoSidebarWidth number | null null Conversation info sidebar width the user dragged to; null means the default 380 px
sendShortcut SendShortcut ("enter" | "mod-enter") "enter" Only stored here; the composer does not read it. To make the setting take effect, return it from the host's composerPreferences.sendShortcut; see Host capabilities · composerPreferences

Setters: setDefaultSurface, setRememberGeometry, setSendShortcut, rememberGeometryNow, setDockWidth, setInfoSidebarOpen, setInfoSidebarWidth.

Persistence

Export Description
installChatSurfaceStorage(storage) Call once at startup with a ChatSurfaceStorage (localStorage works). Reloads both stores
setChatSurfaceStorage(storage) Only sets the storage, without reloading
clearPersistedChatSurfaces(storage) Import from @openmaxai/chat/surfaces/store. Deletes the stored windows directly, whether or not they were loaded; use it when the account changes

Without it everything stays in memory and the windows are gone after a reload. The storage keys are cws-floating-chats (windows) and cws-chat-preferences (preferences). What is stored is each window's id, title, position, size and state, not the conversation itself or its messages: after a reload you fetch the conversation again (hydrate), so a deleted conversation, or one the user was removed from, does not leave a window that cannot open.

Capabilities

The two SDK components must be inside ChatProvider; the window body needs the same capabilities as the conversation header and message area on the main page, see Header and Message thread. When you assemble it yourself, the surfaces themselves read no host capability other than i18n, which button labels ask first; which capabilities a window body needs depends on the components you put in it. What the surfaces themselves depend on:

Dependency Without it
The host's i18n capability, or an I18nextProvider Inside ChatProvider button labels ask i18n first and fall back to useTranslation for keys it does not know; when neither has them they show as keys. See Internationalization
installChatSurfaceStorage Windows and preferences live only in memory; after a reload the windows are gone. See Persistence
container While it is null, floating windows, the dock and the drawer do not render; the docked column does

Accessibility

  • The minimize and close buttons and the avatars in the dock have accessible names (the dock avatars use the conversation title).
  • The docked tab strip is a role="tablist" of role="tab" elements with aria-selected; ← / → move between tabs and wrap around at the ends. The "Show more" button has aria-expanded.
  • The docked column's resize handle is a role="separator" in the Tab order, with aria-valuenow, aria-valuemin and aria-valuemax; ← / → resize it by 16 px.
  • Moving and resizing floating windows needs a pointer; there is no keyboard way. Window position does not affect what you can do, and closing and minimizing have buttons.
  • The drawer's title is the conversation title. With renderPane the visible title is replaced by the conversation header and the title stays for screen readers; the header has a close button, so the drawer can be closed without the swipe gesture.

FAQ

After a reload the window is back, but empty. The conversation itself is not persisted. When the body finds chat.conversation empty, fetch it again and call hydrate; see The window body.

After a reload all windows are gone. installChatSurfaceStorage was not called, so everything was kept in memory only.

A menu or dialog opened from a floating window appears behind the window. With a custom header, pass chrome.overlayContainer to the header (the overlayContainer prop of ChatHeader). The surfaces handle popovers in the body themselves.

The docked column covers the content instead of narrowing it. ChatDockColumn must be a sibling of the main content in the same flex row. Do not portal it or position it absolutely.

My own drawer or dialog closes when I click a floating window. Call isChatSurfaceInteraction(event) in its onInteractOutside and preventDefault() when it returns true; see Installation · Your own drawers and dialogs.