OpenMax
Free Trial

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 what search returns, the candidate insert receives and the panel's candidates (in Panel) 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:30 opens no panel.
  • The panel renders exactly one row per entry in candidates; ArrowUp / ArrowDown, Enter and Escape are handled by the SDK.
  • Hover highlighting uses onMouseOver, not onMouseEnter. Inside ChatShadowRoot, when the pointer moves straight from a React-rendered node on your page into the panel, React never fires onMouseEnter there: 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 (mouseout and mouseover) reach different listeners and the root-side half sees the shadow host instead of the real target. onMouseOver bubbles normally and is safe to call again. The SDK only changed its own components: any onMouseEnter / onPointerEnter you put inside ChatShadowRoot yourself (not just in this panel) is still lost the same way, so use onMouseOver / onPointerOver for anything that should react to hover.
  • titleKey is translated by the host's i18n capability, so add emojiShortcode.tooltip to your translations.
  • It inserts plain text, so it needs no nodes, and no sendKeys or contributeSend. It has no requiredPorts, 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, set emoji-shortcode to "bar" in ChatProvider's toolbarPlacement.
  • 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