From dc0cf94dc3f1f9de45405164620627b4a38a47aa Mon Sep 17 00:00:00 2001 From: rajdubey Date: Fri, 7 Aug 2026 20:52:31 +0530 Subject: [PATCH] docs(ui-kit/react): reconcile contradictory plugin precedence (ENG-37996) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v7 plugin docs contradicted each other on whether custom plugins override built-in ones. overview.mdx and custom-plugin.mdx claimed custom plugins are "appended after the defaults" so "default plugins keep priority", while text-formatters.mdx claimed they are "prepended before the defaults" and take precedence. Verified against the shipped @cometchat/chat-uikit-react v7.1.0 source: - CometChatProvider builds `[...plugins, ...defaultPlugins]` (user plugins first) - CometChatPluginRegistry resolves with `.find()` (first match wins) So custom plugins ARE prepended and DO take precedence — text-formatters.mdx was correct. Fix overview.mdx and custom-plugin.mdx to match, and add a note that precedence is by plugin order + messageTypes/messageCategories, not `id`. Co-Authored-By: Claude Opus 4.8 (1M context) --- ui-kit/react/plugins/custom-plugin.mdx | 2 +- ui-kit/react/plugins/overview.mdx | 8 ++++++-- ui-kit/react/plugins/text-formatters.mdx | 2 +- 3 files changed, 8 insertions(+), 4 deletions(-) diff --git a/ui-kit/react/plugins/custom-plugin.mdx b/ui-kit/react/plugins/custom-plugin.mdx index e12959a5f..a0b3dab77 100644 --- a/ui-kit/react/plugins/custom-plugin.mdx +++ b/ui-kit/react/plugins/custom-plugin.mdx @@ -121,7 +121,7 @@ function App() { } ``` -Your plugin is appended after the default plugins. Since resolution is first-match, default plugins handle their types first, and your plugin handles `"location"` messages. +Your plugin is prepended before the default plugins. Since resolution is first-match, your custom plugins take precedence for the types they declare — here the plugin handles `"location"` messages, a type no built-in plugin claims. To override a built-in type instead, declare the same `messageTypes`/`messageCategories` as the default plugin. ## Step 3: Send a Location Message diff --git a/ui-kit/react/plugins/overview.mdx b/ui-kit/react/plugins/overview.mdx index 2d525be49..5b466ef20 100644 --- a/ui-kit/react/plugins/overview.mdx +++ b/ui-kit/react/plugins/overview.mdx @@ -60,7 +60,7 @@ When the UI Kit needs to render a message, it asks the **Plugin Registry** to fi 1. If the message is deleted (`getDeletedAt() !== null`), the Delete plugin handles it 2. Otherwise, the registry finds the first plugin whose `messageTypes` includes the message's type AND whose `messageCategories` includes the message's category -3. First match wins — plugin order matters +3. First match wins — plugin order matters. Custom plugins passed via the `plugins` prop are placed **before** the defaults, so a custom plugin can override a built-in one for the same type ``` Message { type: "image", category: "message" } @@ -69,11 +69,15 @@ Message { type: "image", category: "message" } → ImagePlugin.renderBubble() is called ``` + +Precedence is determined by **plugin order** (your custom plugins first, defaults after) and matched by `messageTypes` + `messageCategories` — **not** by `id`. The `id` field is a required unique identifier for the plugin; it is not the override mechanism. + + --- ## Adding Plugins -All default plugins are always included. To add your own custom plugins, pass them via the `plugins` prop on `CometChatProvider`. They are appended after the defaults, so default plugins keep priority for their message types: +All default plugins are always included. To add your own custom plugins, pass them via the `plugins` prop on `CometChatProvider`. They are **prepended before the defaults**, so a custom plugin takes priority for its message types (first match wins) — letting you override a built-in plugin by declaring the same `messageTypes`/`messageCategories`: ```tsx import { CometChatProvider } from "@cometchat/chat-uikit-react"; diff --git a/ui-kit/react/plugins/text-formatters.mdx b/ui-kit/react/plugins/text-formatters.mdx index e908319ad..13def11c9 100644 --- a/ui-kit/react/plugins/text-formatters.mdx +++ b/ui-kit/react/plugins/text-formatters.mdx @@ -139,7 +139,7 @@ import { CustomTextPlugin } from "./plugins/CustomTextPlugin"; ``` -Since user plugins are prepended before the defaults in the registry, your custom text plugin takes precedence over the built-in one (first match wins) +Since user plugins are prepended before the defaults in the registry, your custom text plugin takes precedence over the built-in one (first match wins). ## Formatter Details