OpenMax
Free Trial

Header

The bar above a conversation, with title, status, typing line, group info button, the agent model selector and the planned agent run entry.

header-group demo

Screenshot of this demo. It runs on an in-memory sample host (useDemoHost from the demo kit, which is not part of the packages); in your app, pass the host from createChatHost() instead.

Demo source (uses the docs demo kit and Tailwind CSS classes, so it cannot be copied as is): header-group.tsx
"use client";

import { ChatHeader } from "@openmaxai/chat/header";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
import { useState } from "react";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { useDemoData, useDemoHost, useIsCompact } from "./kit";

export default function GroupHeaderDemo() {
	const host = useDemoHost();
	const { conversations, lang } = useDemoData();
	const isCompact = useIsCompact();
	const [infoOpen, setInfoOpen] = useState(false);
	const group = conversations[0];

	return (
		<ChatHostProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				<ChatHeader
					conversation={group}
					headerTitle={group.name ?? ""}
					headerSubtitle={lang === "zh" ? "4 位成员" : "4 members"}
					isAgentCollab={false}
					isObserving={false}
					collabAgents={[]}
					typingText={null}
					mode={isCompact ? "compact" : "full"}
					infoPanelOpen={infoOpen}
					// Without this callback the header draws no info-panel button.
					onToggleInfoPanel={() => setInfoOpen((open) => !open)}
				/>
				<div className="flex min-h-0 flex-1">
					{/* In a row, the thread must fill the remaining width itself, or it shrinks to its content and no longer lines up with the header. */}
					<div className="flex min-w-0 flex-1 flex-col">
						<MessageThread conversation={group} />
					</div>
					{infoOpen && (
						<aside className="w-56 shrink-0 border-l p-4 text-muted-foreground text-sm">
							{lang === "zh"
								? "infoPanelOpen 为 true 时,在这里放你的群信息面板。"
								: "infoPanelOpen is true: put your group info panel here."}
						</aside>
					)}
				</div>
			</div>
		</ChatHostProvider>
	);
}

The demo uses an in-memory host (useDemoHost). In a real app the host comes from createChatHost; ChatHeader only needs to render inside its provider.

When to use

  • Above a MessageThread, which does not render a header itself.
  • Your app computes the title, subtitle and badge; the header doesn't classify conversations.
  • The trailing slot holds your own controls, such as minimize / close on a floating window.

Examples

The first section uses the SDK's ConversationHeader; the ones after it use ChatHeader from @openmaxai/chat/header, which has no style root: the SDK stylesheet applies only inside the .omx-chat component root each SDK component brings along, and ChatRoot is not a style scope itself, so it renders unstyled as written. To use it, put it inside ChatRoot and wrap it in an element with the class omx-chat (plus omx-dark in dark mode, with colorScheme="dark" on ChatRoot), or style it yourself; with a host from createChatHost, use ConversationHeader. A wrapper alone is not enough: outside ChatRoot, dialogs, menus and popovers portal to document.body, outside your wrapper, and get no styles; within ChatRoot they land in its overlay container, which carries the class omx-chat.

SDK conversation header

header-sdk demo

Screenshot of this demo. It runs on an in-memory sample host (useDemoHost from the demo kit, which is not part of the packages); in your app, pass the host from createChatHost() instead.

Demo source (uses the docs demo kit and Tailwind CSS classes, so it cannot be copied as is): header-sdk.tsx
"use client";

import {
	ChatProvider,
	ConversationHeader,
	CwsMessageThread,
	createChatHost,
} from "@openmaxai/chat-sdk/react";
import { createMemoryAdapter } from "@openmaxai/chat-sdk/testing";
import { useEffect, useMemo } from "react";
// Docs helpers: page language and the toast line at the bottom of the demo.
import { useDemoData, useDemoNotify } from "./kit";

export default function SdkHeaderDemo() {
	const { lang, members } = useDemoData();
	const notify = useDemoNotify();
	// In your app the host comes from createChatHost() with your adapter. The memory adapter
	// implements `conversations.setMuted`, so the header shows the mute toggle.
	const host = useMemo(
		() =>
			createChatHost({
				adapter: createMemoryAdapter({
					me: members[0],
					people: members.slice(1),
					conversations: [
						{
							id: "design",
							name: lang === "zh" ? "设计评审" : "Design review",
							messages: [
								{
									senderId: members[1]?.memberId ?? "me",
									text: lang === "zh" ? "稿子发群里了" : "Mockups are in",
								},
							],
						},
					],
				}),
				locale: lang === "zh" ? "zh-CN" : "en",
				ports: { attention: { notify, setUnreadSignal: () => {} } },
			}),
		[lang, members, notify],
	);
	useEffect(() => () => host.dispose(), [host]);
	const conversation = {
		id: "design",
		type: "GROUP" as const,
		name: lang === "zh" ? "设计评审" : "Design review",
		created_at: "2026-10-01T00:00:00Z",
		last_message_at: "2026-10-01T00:00:00Z",
		unread_count: 0,
		member_count: members.length,
		is_observer: false,
	};

	return (
		<ChatProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				{/* Title, member count and mute come from the conversation; on a narrow
				    screen `onBack` adds a back arrow. */}
				<ConversationHeader
					conversation={conversation}
					onBack={() => notify("info", "onBack()")}
				/>
				<CwsMessageThread conversation={conversation} />
			</div>
		</ChatProvider>
	);
}

With createChatHost, render ConversationHeader: title, avatar, badge and member count come from the conversation and match its row in the conversation list. It reads the latest list row with the same id, so it follows mute, member count and rename; when the conversation is not in the loaded list (hidden, opened from a link), the mute toggle reads the result of the last successful change (dropped once you switch to another conversation); opening it from a link again after a successful mute change reads the new state.

conversation-pane.tsx

import { ConversationHeader, CwsMessageThread } from "@openmaxai/chat-sdk/react";

<ConversationHeader
  conversation={selected}
  onBack={() => setSelected(null)}
  trailing={<MyButton />}
/>;
<CwsMessageThread conversation={selected} />;
  • Mute: the toggle appears when the host has conversations.setMuted (the OpenMax adapter does), not for observed conversations; failures go through attention.notify.
  • Back: the back arrow shows only on narrow screens (viewport under 768 px) and when onBack is passed. For a one-column-at-a-time layout use ChatSplitLayout; browser back needs your app to wire history itself.
  • Group info: the button appears only with onToggleInfoPanel, and only in groups. The Chat SDK's ConversationHeader also needs the host to have groupManagement and the conversation not to be observed; otherwise it is not drawn even when passed. trailing renders at the far right.
  • Typing indicator and peer presence: the subtitle line shows the typing indicator; in a DM with an Agent it shows the peer's online status (from the member profile and presence signals; nothing is drawn while the status is unknown rather than guessing "offline", and a billing-suspended peer still shows "Paused · unpaid"). What is still missing is in Known limitations. Props are in the API reference.

Group conversation

conversation-header.tsx

import { ChatHeader } from "@openmaxai/chat/header";

<ChatHeader
  conversation={conversation}
  headerTitle={titleFor(conversation)}
  headerSubtitle={`${memberCount} members`}
  isAgentCollab={conversation.type === "BRIDGE"}
  isObserving={conversation.is_observed === true}
  collabAgents={[]}
  typingText={null}
  infoPanelOpen={infoOpen}
  onToggleInfoPanel={() => setInfoOpen((v) => !v)}
/>;

The info button opens ChatInfoPanel. It appears only for GROUP conversations when you pass onToggleInfoPanel.

Agent DM with the model selector

header-agent-dm demo

Screenshot of this demo. It runs on an in-memory sample host (useDemoHost from the demo kit, which is not part of the packages); in your app, pass the host from createChatHost() instead.

Demo source (uses the docs demo kit and Tailwind CSS classes, so it cannot be copied as is): header-agent-dm.tsx
"use client";

import { ChatHeader } from "@openmaxai/chat/header";
import { ChatHostProvider } from "@openmaxai/chat/host";
import { MessageThread } from "@openmaxai/chat/message-thread";
// Docs helpers: useDemoHost() is an in-memory host with sample data (no backend).
// In your app, pass the host from createChatHost() or your own ChatHost instead.
import { AGENT, useDemoData, useDemoHost, useIsCompact } from "./kit";

export default function AgentDmHeaderDemo() {
	// The demo host provides `agentConfig` (model selector) and `profileCard` (clickable avatar).
	const host = useDemoHost();
	const { conversations } = useDemoData();
	const isCompact = useIsCompact();
	const dm = conversations.find((c) => c.id === "helper");
	if (!dm) return null;

	return (
		<ChatHostProvider host={host}>
			<div className="flex h-full flex-col bg-background text-foreground">
				<ChatHeader
					conversation={dm}
					headerTitle={dm.name ?? ""}
					headerSubtitle={null}
					isAgentCollab={false}
					isObserving={false}
					collabAgents={[]}
					dmPeerStatus="online"
					typingText={null}
					mode={isCompact ? "compact" : "full"}
					infoPanelOpen={false}
					// Your own agent: the header shows the model selector for it.
					isAgentOwnerDm
					agentModelMemberId={AGENT}
				/>
				<MessageThread conversation={dm} />
			</div>
		</ChatHostProvider>
	);
}

In a DM with an agent you own, the header can switch the model and toggle whether its name is visible to others.

<ChatHeader
  /* …required props */
  isAgentOwnerDm
  agentModelMemberId={agentMemberId}
/>

Without agentModelMemberId nothing is drawn. The data comes from the host's agentConfig capability:

agent-config.ts

import type { ChatAgentConfigPort } from "@openmaxai/chat/host";

export const agentConfig: ChatAgentConfigPort = {
  async loadModelState(agentMemberId) {
    const res = await api.getAgentModel(agentMemberId);
    if (!res.ok) return undefined; // the header shows a disabled placeholder
    return {
      effectiveModel: res.body.active,
      desiredModel: res.body.requested,
      applyState: res.body.pending ? "applying" : "ready",
      visible: res.body.public,
      configurable: res.body.canEdit,
      availableModels: res.body.choices.map((c) => ({ key: c.id, displayName: c.label })),
    };
  },
  setModel: (agentMemberId, model) => api.setAgentModel(agentMemberId, model),
  setModelVisibility: (agentMemberId, visible) => api.setAgentModelVisibility(agentMemberId, visible),
};
  • Resolve undefined from loadModelState when the model can't be read; don't throw.
  • setModel resolving means "accepted". The header reloads the state and shows "applying" until applyState is ready.
  • For someone else's agent, pass dmPeerModelLabel for a read-only label.

With @openmaxai/chat-sdk, the adapter's agentConfig has this same type under the SDK's own name, ChatSdkAdapterAgentConfig, so the adapter needs no import from @openmaxai/chat/host.

Single-column layouts and floating windows

<ChatHeader
  /* …required props */
  mode="compact"
  onBack={() => setSelectedId(null)}
  trailing={<WindowControls />}
/>

The back arrow shows only when you pass onBack; you decide when, for example only in a layout that shows one column at a time. The header's layout follows the width of its container, so you don't tell it whether it is on mobile; see Responsive behavior.

If the header sits in a floating layer above your app's overlays, pass overlayContainer so its popovers render inside that layer.

Agent run entry

Planned

Once the host provides the agentRuns capability, the header shows an entry for each agent with unfinished runs, such as "Assistant · 2 running · 1 queued". Opening it shows that agent's runs in this conversation (AgentRunList).

Today: run summary (transitional)

Transitional

Until the run entry above lands, a header under the Chat SDK already shows a one-line run summary, which is read-only progress (experimental · transitional). While the host's agentActivity has a run in this conversation that is in progress (queued, thinking or calling a tool) and not out of sync, ConversationHeader shows the summary where the subtitle goes, ahead of the typing indicator; when all runs end (terminal, out of sync, evicted, scope ended) it falls back to the typing indicator below. ChatHeader does not compute it: the text comes in through typingText as well.

Runs in progress Shows (key in the chat namespace)
One, queued "Assistant is waiting" (agentRun.header.queued); in a DM the current user is in, no name: "Waiting" (agentRun.state.queued)
One, working "Assistant is working" (agentRun.header.working); in a DM the current user is in, no name: "Working" (agentRun.state.working)
Two or more from the same Agent "Assistant is working (2 messages)" (agentRun.header.workingCount), "Assistant is waiting (2 messages)" (agentRun.header.queuedCount) when all are queued; in a DM the current user is in, no name: "Working (2 messages)" (agentRun.state.workingCount) / "Waiting (2 messages)" (agentRun.state.queuedCount)
Two or more Agents "2 Agents are working" (agentRun.header.many), counting distinct Agents, not runs

The name comes from this conversation's members, "Unknown member" when not found. The header shows a fixed state only, not what the agent is doing; that is in the run block in the message thread. The run entry above replaces it when the planned Agent runs capability lands.

Typing indicator

When someone other than the current user is typing in the conversation, the header shows it where the subtitle goes, over the peer status and the subtitle. ChatHeader does not compute it: the text comes in through typingText; with the Chat SDK, ConversationHeader computes it for you (from the typing signals handed over by the adapter's realtime).

Who is typing Shown (key in the chat namespace)
The other person in a DM the current user is in "Typing…" (typing.peer)
Otherwise, one person "Alice is typing…" (typing.one; "Unknown member" when the name is not found)
Otherwise, two or more "3 people are typing…" (typing.many)
  • Other people only. Typing on another tab or device of your own is not shown; nothing is shown until the current user is known (GET /me has returned).
  • Expires on its own. It goes away 6 seconds after the last "start" with no new one; a "stop" removes it at once. A new message from that person does not clear it early.
  • Agents are shown too.
  • Whether observers see it is up to the backend: OpenMax currently sends typing only to conversation members.
  • Your own typing is not shown to others: the Chat SDK does not send typing yet; see Known limitations.

The data comes from typing signals; see Realtime and sync · Realtime signals. Conversation list rows do not show typing.

API

Prop Type Default Description
conversation ChatConversation required The open conversation
headerTitle string required Title
headerSubtitle string | null required Subtitle; agent DMs show the agent's status instead
isAgentCollab boolean required Agent collaboration conversation; shows the collaborating agents
isObserving boolean required The viewer observes this conversation (read-only)
collabAgents CollabAgent[] required Agents shown for a collaboration conversation
typingText string | null required The "is typing" text, see Typing indicator; null hides it
infoPanelOpen boolean required Pressed state of the info button
dmPeerStatus OnlineStatus — DM peer's online status
peerStatusAvailable boolean true Whether the peer's online status is known. With false, the Agent DM status line only shows when the peer is suspended for billing, never "offline"
mode "full" | "compact" "full" Density (spacing only). compact for mobile and floating windows
showIdentity boolean true Whether to render the conversation's avatar and name. The docked column passes false (the tab already shows them); everything else is unaffected
inlineMeta boolean false Put the status line (typing / peer status / subtitle) and the badges / model on one non-wrapping line, status first; the name (when shown) gets its own line above. The docked column and the drawer pass true; badges and the model name truncate instead of wrapping
onBack () => void — Back arrow handler; the arrow shows when it is passed
onToggleInfoPanel () => void — Group info button; none when omitted, and none when onToggleInfoSidebar is passed
onToggleInfoSidebar () => void — Conversation info sidebar button, for every conversation type; replaces the group info button. None when omitted. @experimental
infoSidebarOpen boolean false Whether that sidebar is open: the button's pressed look and aria-expanded
infoSidebarId string — id of the sidebar element; set as the button's aria-controls while it is open
isMuted boolean false Muted: the toggle shows a crossed-out bell
onToggleMute () => void — Mute toggle handler; no toggle when omitted
muteDisplay "toggle" | "marker" "toggle" How mute shows: "toggle" is an always-present bell; "marker" draws no bell, only a "Muted" marker after the name while muted, which calls onToggleMute (to unmute). Applies to groups only: other conversations keep the bell. Used with the conversation info sidebar. @experimental
memberCounts { people: number; agents: number } | null null People and Agents in the group. For a group, together with onOpenMembers, the member count under the name becomes "N people · N Agents", two buttons; otherwise the subtitle shows as given. @experimental
onOpenMembers (tab: "people" | "agents") => void — One of those two counts was clicked: open the member list on that page. @experimental
onOpenPeerInfo () => void — Given ⇒ in a DM the peer's avatar and name are buttons that call this (open the conversation info sidebar on its "Info" tab) instead of popping up the peer's profile card. Observed DMs get them too (unlike the card; the sidebar is their read-only view); not DMs with a system member, Agent collaboration conversations or groups. @experimental
onPopOut () => void — "Pop out to floating window" button after mute and group info; none when omitted. Whether a window can open here is up to you
isAgentOwnerDm boolean false Viewer owns the agent in this DM: owner badge and model selector
agentModelMemberId string — Agent member id to configure. Read only when isAgentOwnerDm
dmPeerModelLabel string | null — Read-only model label for someone else's agent
badge ChatHeaderBadge | null null { label, bg, color } pill next to the title
trailing ReactNode — Rightmost slot
rootProps ComponentPropsWithoutRef<"div"> — Extra props on the root; className is merged
overlayContainer HTMLElement | null — Where popovers and dialogs portal to

CollabAgent is { name: string; online_status?: OnlineStatus | null } and OnlineStatus is "online" | "starting" | "stopping" | "offline" | "error" | "unknown" (the same as a member's online_status in the Data model). Both types are exported from @openmaxai/chat/header Planned.

Capabilities

Capability Without it
agentConfig Owner DMs show a disabled placeholder where the selector would be
profileCard The DM avatar and name are not clickable. See Profile card
agentRuns Planned No agent run entry
The adapter's realtime (typing / presence signals, ConversationHeader) No typing indicator; presence in an Agent DM comes only from member profiles and does not follow live changes
The adapter's profiles (ConversationHeader) Presence in an Agent DM appears only after the first presence signal; with neither, the status line only shows when the peer is suspended for billing

Accessibility

  • The back button, owner badge button and model selector are labelled. The selector sets aria-busy while applying and reports failures with role="alert".
  • The group info button is icon-only and gets its accessible name from aria-label. Planned
  • The typing indicator and the peer status are not in a live region: changes are not announced; screen reader users read them with the rest of the header.

FAQ

The info button doesn't show up. It needs a GROUP conversation and onToggleInfoPanel.

The model selector is missing or greyed out. Pass both isAgentOwnerDm and agentModelMemberId. Greyed out means the host has no agentConfig, loadModelState returned undefined, or the state has configurable: false or no availableModels.