Write a composer plugin
Write a composer plugin with defineComposerPlugin and pass it to ChatProvider next to the default plugins.
Write a composer plugin
The built-in emoji plugin picks an emoji from a panel opened by a button. This page builds a different one, an emoji shortcode plugin: typing : plus a few letters opens emoji candidates, and picking one inserts the emoji; a button in the + menu inserts :. It uses only two abilities, the trigger and candidate panel and a toolbar button, and needs no extra capability from the host.
Define the plugin
emoji-shortcode-plugin.tsx
import { defineComposerPlugin } from "@openmaxai/chat/composer";
interface EmojiCandidate {
id: string; // unique among the candidates; used for keyboard highlight and list keys
emoji: string;
}
const EMOJIS: EmojiCandidate[] = [
{ id: "smile", emoji: "😄" },
{ id: "thumbsup", emoji: "👍" },
{ id: "tada", emoji: "🎉" },
];
function SmileIcon({ className }: { className?: string }) {
return <span className={className} aria-hidden>🙂</span>;
}
export const emojiShortcodePlugin = defineComposerPlugin<EmojiCandidate>({
id: "emoji-shortcode",
trigger: {
chars: [":", ":"],
// No panel for a bare ":"
search: (query) =>
query ? EMOJIS.filter((e) => e.id.startsWith(query.toLowerCase())) : [],
// Replace ":" and the typed letters with the emoji
insert: (view, range, candidate) => {
view.dispatch(view.state.tr.insertText(`${candidate.emoji} `, range.from, range.to));
view.focus();
},
Panel: ({ candidates, activeIndex, onSelect, onActiveIndexChange }) => (
<ul role="listbox" className="rounded-md border bg-popover p-1 text-sm">
{candidates.map((c, i) => (
<li
key={c.id}
role="option"
aria-selected={i === activeIndex}
className={i === activeIndex ? "rounded bg-accent px-2 py-1" : "px-2 py-1"}
onMouseOver={() => onActiveIndexChange(i)}
onMouseDown={(e) => {
e.preventDefault(); // keep focus in the composer
onSelect(i);
}}
>
{c.emoji} :{c.id}:
</li>
))}
</ul>
),
},
toolbar: [
{
id: "emoji-shortcode",
icon: SmileIcon,
titleKey: "emojiShortcode.tooltip",
defaultPlacement: "plus-menu",
onActivate: (ctx) => ctx.activateTrigger(":"),
},
],
});
Points to note:
defineComposerPlugin<EmojiCandidate>makes whatsearchreturns, the candidateinsertreceives and the panel'scandidates(inPanel) one type, so a mismatch is a type error on the spot.- A trigger must follow the start of a line or whitespace, so text like
10:30opens no panel. - The panel renders exactly one row per entry in
candidates;ArrowUp/ArrowDown,EnterandEscapeare handled by the SDK. - Hover highlighting uses
onMouseOver, notonMouseEnter. InsideChatShadowRoot, when the pointer moves straight from a React-rendered node on your page into the panel, React never firesonMouseEnterthere: the chat lives in a portal inside the shadow root, and React listens both on your root container and on that portal container, so the two halves of the enter (mouseoutandmouseover) reach different listeners and the root-side half sees the shadow host instead of the real target.onMouseOverbubbles normally and is safe to call again. The SDK only changed its own components: anyonMouseEnter/onPointerEnteryou put insideChatShadowRootyourself (not just in this panel) is still lost the same way, so useonMouseOver/onPointerOverfor anything that should react to hover. titleKeyis translated by the host'si18ncapability, so addemojiShortcode.tooltipto your translations.- It inserts plain text, so it needs no
nodes, and nosendKeysorcontributeSend. It has norequiredPorts, so every host can install it.
Install it next to the defaults
Put it in one array with COMPOSER_PLUGINS and pass that as plugins on ChatProvider:
app.tsx
import { COMPOSER_PLUGINS } from "@openmaxai/chat/composer";
import { ChatProvider } from "@openmaxai/chat-sdk/react";
import { emojiShortcodePlugin } from "./emoji-shortcode-plugin";
<ChatProvider host={host} plugins={[...COMPOSER_PLUGINS, emojiShortcodePlugin]}>
{/* ConversationList, MessageThread … */}
</ChatProvider>;
- Passing only
[emojiShortcodePlugin]gives you this plugin alone, without@,#or the built-in emoji button. - The array order sets the order of the toolbar buttons. This button sits in the
+menu by default; to show it on the toolbar, setemoji-shortcodeto"bar"inChatProvider'stoolbarPlacement. - A trigger character, node name or button id that clashes with a default plugin throws when the plugin set is assembled; see What throws at assembly.
When the plugin needs host data
A plugin that reads host data (searching people or work items, say) lists the capabilities it uses in requiredPorts and reads them from ctx.host in search or from the panel's host:
interface MemberCandidate {
id: string;
name: string;
}
defineComposerPlugin<MemberCandidate>({
id: "assign",
requiredPorts: ["identity"],
trigger: {
chars: ["~"],
search: async (query, ctx) => {
const page = await ctx.host.identity.searchDirectory({ search: query });
return page.members.map((m) => ({ id: m.memberId, name: m.displayName }));
},
// insert, Panel …
},
});
If the host lacks anything in requiredPorts, the plugin is not installed; see Plugins whose capabilities are missing are skipped. A plugin can only use capabilities that exist on ChatHost.
Types for writing plugins
defineComposerPlugin and these two types are exported from @openmaxai/chat/composer:
| Type | Use |
|---|---|
ComposerPlugin |
A plugin; COMPOSER_PLUGINS is an array of them |
ComposerToolbarPanelProps |
Props of a toolbar button's own panel (close) |
Writing the panel, a button or a node spec as a separate component or constant also takes the following types, which will be exported from @openmaxai/chat/composer:
| Type | Use |
|---|---|
ComposerCandidate |
The minimal candidate shape (just id) your candidate type must satisfy Planned |
ComposerPanelProps |
Props of a candidate panel, as in ComposerPanelProps<EmojiCandidate> Planned |
ComposerToolbarItem |
One toolbar button Planned |
ComposerNodeSpec |
The spec of one content node (a ProseMirror node spec plus toText and chip) Planned |
