Installation
Install the chat components and SDK with their peer dependencies, load the stylesheet, configure your bundler and add the required providers.
Installation
Prerelease
The packages are on npm as
3.0.0prereleases (3.0.0-beta.*). Every export is@experimentaland may change between prereleases, so pin an exact version (for example3.0.0-beta.5) and use the same one for every@openmaxai/chat*package.
Requirements
- React 19
You do not need Tailwind CSS: the SDK ships a precompiled stylesheet.
Install the packages
pnpm add @openmaxai/chat@3.0.0-beta.5 @openmaxai/chat-store@3.0.0-beta.5 @openmaxai/chat-sdk@3.0.0-beta.5 @openmaxai/chat-openmax@3.0.0-beta.5 react-i18next i18next
The command pins every @openmaxai/chat* package to the same exact version (3.0.0-beta.5 here; change them together). If you connect your own backend and not OpenMax, leave out @openmaxai/chat-openmax.
| Package | Provides |
|---|---|
@openmaxai/chat |
The chat components and the ChatHost type |
@openmaxai/chat-store |
The chat's data store, shared by @openmaxai/chat and @openmaxai/chat-sdk. List it yourself: there must be exactly one copy on the page |
@openmaxai/chat-sdk |
createChatHost({ adapter }) (builds a host from the adapter you pass; it does not take OpenMax connection options), createLocalPorts (local defaults for a host), createChatI18n (the strings instance for the chat) and the precompiled stylesheet @openmaxai/chat-sdk/styles.css |
@openmaxai/chat-openmax |
For the OpenMax backend: createChatHost(config) from @openmaxai/chat-openmax/react builds a host connected to OpenMax from baseUrl, wsUrl and auth; see Connect to OpenMax. Not needed when you connect your own backend |
react-i18next, i18next |
Peer dependencies (react-i18next ^17.0.8, i18next ^26.3.2). The chat components read their strings through your copy of react-i18next; I18nextProvider and useTranslation always come from it |
@tanstack/react-query |
Optional peer dependency of @openmaxai/chat (^5), used only by MessageThread from @openmaxai/chat/message-thread |
You must install @tanstack/react-query@5 when you use MessageThread from @openmaxai/chat/message-thread; this requirement will be removed in a later version. @openmaxai/chat-sdk itself does not use it.
react and react-dom 19 are peer dependencies too; a React 19 project already has them.
Install every @openmaxai/chat* package at the same version
@openmaxai/chat,@openmaxai/chat-store,@openmaxai/chat-sdkand, when you connect to OpenMax,@openmaxai/chat-openmaxmust all be the same version: give the same version or the same dist-tag to every one of them.@openmaxai/chat-sdkdeclares@openmaxai/chatand@openmaxai/chat-storeas peer dependencies of its own exact version (@openmaxai/chat-openmaxdoes the same for@openmaxai/chat,@openmaxai/chat-storeand@openmaxai/chat-sdk), so a mismatch shows up when you install:
- npm stops with an
ERESOLVEerror and installs nothing. Align the versions; do not get past it with--forceor--legacy-peer-deps.- pnpm installs anyway and prints an
unmet peerwarning. Do not ignore it: align the versions. (pnpm'sstrictPeerDependenciessetting makespnpm installfail on it, butpnpm addstill only warns.)- yarn 1 does not install peer dependencies for you and only warns on a mismatch, so list
@openmaxai/chatand@openmaxai/chat-storein your own install command, as the command above does.Mismatched copies keep separate state and React context, so things break silently: a floating window you open from one copy never shows. If they still end up on the page, the SDK logs
Package version mismatchto the console, once for each mismatched package version (a copy that loads later is reported when it arrives), and in development<ChatProvider>throwsChatSdkConfigErrorwith the same message. Check withnpm ls @openmaxai/chat @openmaxai/chat-storeorpnpm why @openmaxai/chat @openmaxai/chat-store; each package should resolve to a single version. Releases up to3.0.0-beta.1declare these packages as regular dependencies: a different version is installed as a second copy without any error or warning, and the SDK does not report it, so keep the versions in step yourself.
Planned agent runs need no separate @ag-ui/core install: @openmaxai/chat will depend on it (1.0.x) and re-export its event type as AgUiEvent; see Connect your own backend. Planned
Load the styles
Import the SDK's stylesheet once, in your global CSS:
src/globals.css
@import "@openmaxai/chat-sdk/styles.css";
The stylesheet is precompiled: it contains the CSS variables, the base styles and every class the chat
components use. There is no Tailwind setup, no @source and no PostCSS plugin to add. You can also
import it from JavaScript (import "@openmaxai/chat-sdk/styles.css"; in your entry file).
Then put the chat inside ChatRoot (from @openmaxai/chat-sdk/react). ChatRoot gives the SDK
components inside it their color scheme and overlay landing node; each SDK component inside it brings its
own .omx-chat component root, and every rule in the stylesheet is scoped to those component roots.
Components outside a ChatRoot render unstyled, with no error:
import { ChatProvider, ChatRoot } from "@openmaxai/chat-sdk/react";
<ChatProvider host={host}>
<ChatRoot colorScheme="light" style={{ height: "100%" }}>
{/* your layout: CwsConversationList, CwsMessageThread, … */}
</ChatRoot>
</ChatProvider>;
What this gives you:
Your page is left alone. The stylesheet has no rules for
html,bodyor:rootand none outside.omx-chat: your root font size, scrollbars,bodybackground and text color, and your own elements stay as they are. If your app also uses Tailwind CSS v4, our copy of its base reset only applies to the SDK components' own nodes.Nodes you put inside
ChatRootkeep your styles. Your own layout and content placed directly inChatRoot, and content you put into an SDK component's slot (list/childrenofChatSplitLayout,trailingofConversationHeader,emptyStateofCwsMessageThread,childrenofResizableConversationListColumn, and the body drawn by message-display plugins you install throughChatProvider'smessageRenderers, and the panels and slots of composer plugins you install throughplugins:Panel,trigger.Panel,PlusSlot,LeadingSlot; toolbar icons take theclassNamewe pass and keep the chat's look), are not touched by our base reset: your utilities such asm-autoor a border color work as usual, whether or not they sit in an@layer. Inheritance and same-named variables inside slots are covered in Known limitations.Your element and universal rules lose only on the properties the chat sets. On the SDK components' nodes, rules such as
button {},a {},h1 {}or* {}(inside an@layeror not) lose to the chat's own styles for what those styles set: box sizing, margins, padding and borders on every element, the background, font and color of buttons, the color of links, the size of headings, and whatever the chat's classes set on an element. Properties the chat does not set, such asletter-spacing,word-spacingortext-transform, still apply from your rules, and inherited properties you set on an ancestor ofChatRootcarry into the chat. Class rules with the same names as ours and high-specificity rules also still reach it; see Known limitations. To keep all of these out, embed the chat withChatShadowRootinstead (see Embed in Shadow DOM): your rules no longer match the chat's elements, and a reset layer inside the shadow root stops the inherited properties that still cross the shadow boundary (your* {}rule also matches the shadow host and passes itsletter-spacingdown).Overlays stay in the scope. Menus, tooltips, dropdowns, dialogs and drawers opened in the chat render into a landing node at the end of the
ChatRootcontainer (the node carries.omx-chatitself), not intobody, so they keep the chat's styles and dark mode.No name clashes on animations. The chat's
@keyframesare namedomx-*, so your ownenterorspinkeyframes do not change its animations.Dark mode comes from
colorScheme. Adarkclass on your<html>does not affect the chat; see Theming.
The chat's sizes are based on --omx-rem (default 16.8px), not on your root font size; see
Theming · Size.
Floating surfaces and overlayContainer
ChatFloatingSurfaces and ChatDockColumn also go inside ChatRoot (in the React tree):
ChatFloatingSurfacesportals into thecontaineryou give it (usuallydocument.body). InsideChatRootit first puts a node with the scope classes anddisplay: contentsinto that container, and the floating windows, the minimized dock and the small-screen drawer render in it.ChatDockColumnrenders where you place it and does not usecontainer. It must be inside the DOM ofChatRoot(orChatShadowRoot), next to your main content: placed outside it, it renders unstyled.
When you mount either of them, also pass overlayContainer, usually "body": the SDK then builds the
landing node at the end of body itself and removes it on unmount. Without it, overlays
opened in the main chat area, and cards dragged out of the dock or a floating window, land inside the
ChatRoot container. If any ancestor of the container creates a stacking context (transform, filter,
contain, isolation, or a z-index on a positioned element), they cannot rise above it and end up
under the floating windows, which live at body level. With overlayContainer they render at body
level too and stack as intended: dragged cards over the floating windows.
import { ChatRoot } from "@openmaxai/chat-sdk/react";
import type { ReactNode } from "react";
export function ChatShell({ children }: { children: ReactNode }) {
return <ChatRoot overlayContainer="body">{children}</ChatRoot>;
}
You can pass a node of your own instead, a direct child of body (if the floating surfaces get their own
container node, put this one after it). While that node is null (before your ref has it), overlays fall
back to body without the chat's styles. "body" has a similar gap, one commit long: in ChatRoot the landing node
is ready one commit after mount, and overlays opened before that also land in body (see Known limitations,
"Overlays use body for the first frame").
The landing node ChatRoot creates in overlayContainer carries the scope classes (and omx-dark), so
overlays keep the chat's styles there. React events from an overlay still bubble through the React tree:
an onClick on a React ancestor of ChatRoot sees clicks inside a menu or dialog even though its DOM node
is under body.
Your own drawers and dialogs
The floating windows sit outside the drawers and dialogs on your page (in the DOM they are another node under body), so clicking a floating window while your drawer is open counts as a click outside it and closes the drawer. In its outside-interaction callback, use isChatSurfaceInteraction from the root entry to leave the chat's floating surfaces out:
host-drawer.tsx
import { isChatSurfaceInteraction } from "@openmaxai/chat-sdk";
<Dialog.Content
onInteractOutside={(event) => {
if (isChatSurfaceInteraction(event)) event.preventDefault();
}}
>
…
</Dialog.Content>
Menus, the emoji picker and dialogs opened inside a floating window count as floating surface too, wherever they are portalled. It is exported from the root entry and does not need React, and it works when your Radix is a different copy from the chat's; without Radix, listen for pointerdown / focusin on document in the bubble phase and pass it the event. Do not use the capture phase: the chat puts its mark on the event during React's event dispatch, which listens on page nodes below document, so a capture listener on document runs before that.
This only stops the outside click from closing it. A modal dialog (the Radix default) also traps focus: it stays open, but the input in the floating window cannot take focus, so nothing can be typed there. To use the floating window while your dialog is open, make the dialog non-modal (modal={false}).
Escape inside your dialog
The chat ships its own copy of Radix, so your Radix layers (dialog, drawer, popover) and the chat's do not see each other. When focus is inside one of the chat's layers (a menu, the emoji picker, a dialog), Escape closes the chat's topmost layer and leaves yours open; the next Escape closes yours. The chat only calls preventDefault() on that Escape and does not stop it, so your Radix layer leaves it alone, and your other listeners still receive it.
Your layer's onEscapeKeyDown is still called for that Escape, with event.defaultPrevented already true. If you do anything there besides closing (analytics, an "unsaved changes" prompt), return early when it is set:
host-dialog.tsx
<Dialog.Content
onEscapeKeyDown={(event) => {
if (event.defaultPrevented) return; // the chat closed one of its own layers
track("host_dialog_escape");
}}
>
…
</Dialog.Content>
Do not call preventDefault() in onEscapeKeyDown to make way for the chat: the chat's copy sees defaultPrevented too, and nothing closes. If you close things on Escape with your own listener instead of Radix, listen on document or in the bubble phase and skip events whose defaultPrevented is true; a capture listener on window can run before the chat has handled the key.
When focus is not inside one of the chat's layers, your layer still takes Escape first, as it would without this handling; see Known limitations.
Embed in Shadow DOM
ChatRoot scopes the chat with class selectors, so some of your page's CSS still reaches it (see
Known limitations). When your page has rules you cannot
change, such as global element or universal rules, classes with the same names as ours or high-specificity
selectors, put the chat into ChatShadowRoot (experimental) instead of ChatRoot. It renders an
<omx-chat-host> element in your page and renders the chat into that element's open shadow root. It is still
the same React tree: your providers and context reach the components inside.
The styles go in through a prop: pass the whole module of the string entry @openmaxai/chat-sdk/styles (its
styles and properties exports). A page that only uses ChatShadowRoot does not import
@openmaxai/chat-sdk/styles.css, and only pages that use Shadow DOM bundle the stylesheet as a string:
import { ChatProvider, ChatShadowRoot } from "@openmaxai/chat-sdk/react";
import * as chatStyles from "@openmaxai/chat-sdk/styles";
<ChatProvider host={host}>
<ChatShadowRoot styles={chatStyles} colorScheme="light" style={{ height: "100%" }}>
{/* your layout: CwsConversationList, CwsMessageThread, … */}
</ChatShadowRoot>
</ChatProvider>;
Compared with ChatRoot:
- Your rules stay out. Element, universal, same-named class and high-specificity rules on your page, and a
darkclass on<html>, match nothing inside the shadow root. Inherited properties set on<omx-chat-host>or its ancestors (letter-spacing,text-align,white-space, …) still cross the shadow boundary; a reset layer inside the shadow root stops them. Custom properties (including--omx-rem) and the writing direction still inherit, on purpose. - Your page is left alone. The stylesheet goes into the shadow root as a constructable stylesheet, one per
document and shared by every instance (a
<style>inside the shadow root where the browser lacks constructable stylesheets). The SDK's own styles stay out of your page'sheadexcept one<style data-omx-chat-properties>holding the@propertyregistrations, which only work at document level; it is written once and never removed. When a different copy arrives later (two SDK versions on one page), the SDK appends it too and logs aconsole.warn; for names both copies register, the browser decides which definition applies. Libraries the SDK uses also write tohead; the ones we know of: vaul appends its own<style>as soon as the SDK loads, and the scroll lock adds one while it is active (see Known limitations). <omx-chat-host>is a box in your layout, block-level by default;classNameandstylego on it. See Theming · The host element in Shadow DOM.- Overlays stay inside the shadow root by default, and their landing node exists before the first render, so
they never fall back to
body. With floating surfaces, passoverlayContainer="body"as above: the SDK builds a small shadow root of its own (an "island", with the same styles) at the end ofbody, and overlays land there. UnlikeChatRoot,overlayContainer={null}means the same as leaving it out: overlays inbodyitself would get none of the chat's styles. - Floating surfaces and the docked column go inside
ChatShadowRootjust as they go insideChatRoot:ChatFloatingSurfacesbuilds an island in itscontainer, andChatDockColumnmust be among thechildrenofChatShadowRoot. - Fonts come from your page. The stylesheet contains no
@font-face: a font declared inside a shadow root is not reliable. To show the chat in a web font, load that font in your page's own CSS, in the outer document; the chat area then finds it by name. - Server rendering outputs only an empty
<omx-chat-host>; the shadow root and the chat appear once it mounts in the browser.
What Shadow DOM solves, what stays and what it adds are in Known limitations · Shadow DOM.
Configure your bundler
Vite
Dedupe React, or a second copy can load and fail with Invalid hook call.
vite.config.ts
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [react()],
resolve: { dedupe: ["react", "react-dom"] },
});
Next.js
Import the stylesheet once in the root layout, and render the chat from a Client Component ("use client"). A module marked "use client" also runs during server-side rendering; to create the host at module scope with REST behind a same-origin proxy, see Connect to OpenMax · Server-side rendering and Next.js.
app/layout.tsx
import "@openmaxai/chat-sdk/styles.css";
Providers
Outermost first:
| Provider | From | Role |
|---|---|---|
I18nextProvider |
react-i18next |
Strings for the mention panel, group management and floating/drawer surfaces; without it they show raw keys. Give it an instance from createChatI18n (@openmaxai/chat-sdk); see Internationalization |
QueryClientProvider |
@tanstack/react-query |
When you use MessageThread from @openmaxai/chat/message-thread: the legacy message thread caches through React Query. A host created by createChatHost does not bring this layer, so it needs one too |
ChatProvider |
@openmaxai/chat-sdk/react |
Installs the host and the composer plugins; the one entry point. Use it for hosts created by createChatHost and for hosts you write yourself; the optional plugins defaults to the built-in plugins |
src/app.tsx
import { createChatI18n } from "@openmaxai/chat-sdk";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { I18nextProvider } from "react-i18next";
import { host } from "./host"; // created by createChatHost
const i18n = createChatI18n({ locale: "en-US" });
export function App() {
return (
<I18nextProvider i18n={i18n}>
<ChatProvider host={host}>
{/* CwsConversationList, CwsMessageThread, … */}
</ChatProvider>
</I18nextProvider>
);
}
createChatI18n creates a separate i18next instance with the chat's strings built in; it leaves your app's own react-i18next setup alone. When you use MessageThread from @openmaxai/chat/message-thread, put a QueryClientProvider between I18nextProvider and ChatProvider. The Quick start uses CwsMessageThread and does not need it.
For a host created by createChatHost, ChatProvider re-renders when the signed-in user's data arrives. Pass the object createChatHost() returns directly and do not spread-copy it ({ ...host }): a spread copy makes ChatProvider throw ChatSdkConfigError.
You don't pick the composer plugins yourself: each plugin declares the capabilities it needs, and the SDK does not install a plugin whose capabilities the host lacks. A host without workItems, for example, gets no # in the composer, and @ still works. To use a different set, pass plugins; writing it inline is fine, because the SDK compares plugins by id and does not rebuild the editor while the ids stay the same (swapping a plugin object under the same id has no effect). Which plugins exist and how to write your own: Plugins.
Next steps
- Core concepts: Host, capability, adapter.
- Quick start: A running chat on in-memory data.
- Connect to OpenMax: Use createChatHost against an OpenMax backend.
