OpenMax
Free Trial

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.0 prereleases (3.0.0-beta.*). Every export is @experimental and may change between prereleases, so pin an exact version (for example 3.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-sdk and, when you connect to OpenMax, @openmaxai/chat-openmax must all be the same version: give the same version or the same dist-tag to every one of them. @openmaxai/chat-sdk declares @openmaxai/chat and @openmaxai/chat-store as peer dependencies of its own exact version (@openmaxai/chat-openmax does the same for @openmaxai/chat, @openmaxai/chat-store and @openmaxai/chat-sdk), so a mismatch shows up when you install:

  • npm stops with an ERESOLVE error and installs nothing. Align the versions; do not get past it with --force or --legacy-peer-deps.
  • pnpm installs anyway and prints an unmet peer warning. Do not ignore it: align the versions. (pnpm's strictPeerDependencies setting makes pnpm install fail on it, but pnpm add still only warns.)
  • yarn 1 does not install peer dependencies for you and only warns on a mismatch, so list @openmaxai/chat and @openmaxai/chat-store in 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 mismatch to the console, once for each mismatched package version (a copy that loads later is reported when it arrives), and in development <ChatProvider> throws ChatSdkConfigError with the same message. Check with npm ls @openmaxai/chat @openmaxai/chat-store or pnpm why @openmaxai/chat @openmaxai/chat-store; each package should resolve to a single version. Releases up to 3.0.0-beta.1 declare 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, body or :root and none outside .omx-chat: your root font size, scrollbars, body background 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 ChatRoot keep your styles. Your own layout and content placed directly in ChatRoot, and content you put into an SDK component's slot (list / children of ChatSplitLayout, trailing of ConversationHeader, emptyState of CwsMessageThread, children of ResizableConversationListColumn, and the body drawn by message-display plugins you install through ChatProvider's messageRenderers, and the panels and slots of composer plugins you install through plugins: Panel, trigger.Panel, PlusSlot, LeadingSlot; toolbar icons take the className we pass and keep the chat's look), are not touched by our base reset: your utilities such as m-auto or 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 @layer or 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 as letter-spacing, word-spacing or text-transform, still apply from your rules, and inherited properties you set on an ancestor of ChatRoot carry 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 with ChatShadowRoot instead (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 its letter-spacing down).

  • 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 ChatRoot container (the node carries .omx-chat itself), not into body, so they keep the chat's styles and dark mode.

  • No name clashes on animations. The chat's @keyframes are named omx-*, so your own enter or spin keyframes do not change its animations.

  • Dark mode comes from colorScheme. A dark class 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):

  • ChatFloatingSurfaces portals into the container you give it (usually document.body). Inside ChatRoot it first puts a node with the scope classes and display: contents into that container, and the floating windows, the minimized dock and the small-screen drawer render in it.
  • ChatDockColumn renders where you place it and does not use container. It must be inside the DOM of ChatRoot (or ChatShadowRoot), 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 dark class 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's head except one <style data-omx-chat-properties> holding the @property registrations, 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 a console.warn; for names both copies register, the browser decides which definition applies. Libraries the SDK uses also write to head; 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; className and style go 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, pass overlayContainer="body" as above: the SDK builds a small shadow root of its own (an "island", with the same styles) at the end of body, and overlays land there. Unlike ChatRoot, overlayContainer={null} means the same as leaving it out: overlays in body itself would get none of the chat's styles.
  • Floating surfaces and the docked column go inside ChatShadowRoot just as they go inside ChatRoot: ChatFloatingSurfaces builds an island in its container, and ChatDockColumn must be among the children of ChatShadowRoot.
  • 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