docs(ui-kit/react): reconcile contradictory plugin precedence (ENG-37996)

ui-kit/react/plugins/custom-plugin.mdx

@@ -4,7 +4,7 @@
 description: "Build a custom message plugin for rendering, context menus, and conversation previews, plus the plugin interface and context reference."
 ---
 
 Custom plugins let you handle any message type with your own rendering logic. This walkthrough builds a complete "Location" plugin that renders a map preview, provides context menu options, and shows a conversation preview.
 
 ## Step 1: Define the Plugin
 
@@ -121,7 +121,7 @@
 }
 ```
 
-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
 
@@ -213,7 +213,7 @@
 | `onMarkAsUnread` | `(msg) => void` | Mark as unread |
 | `onFlagMessage` | `(msg) => void` | Open flag/report dialog |
 | `showToast` | `(text) => void` | Show a toast notification |
 | `getTextFormatters` | `() => Formatter[]` | Get text formatters for caption rendering |
 | `publish` | `(event) => void` | Publish a UI event |
 
 ## Tips

ui-kit/react/plugins/overview.mdx

@@ -41,7 +41,7 @@
 | `renderBubble` | `(message, context) => ReactNode` | Yes | Render the inner bubble content (the outer wrapper is handled by `CometChatMessageBubble`) |
 | `getOptions` | `(message, context) => CometChatMessageOption[]` | Optional | Context menu options for the message (return `[]` for none) |
 | `getLastMessagePreview` | `(message, loggedInUser, t?) => string` | Optional | Plain-text subtitle shown in the Conversations list |
 | `getTextFormatters` | `() => CometChatTextFormatter[]` | Optional | Text formatters this plugin provides (only the text plugin uses this) |
 | `renderLeadingView` | `(message, context) => ReactNode` | Optional | Override the leading view (avatar area) |
 | `renderHeaderView` | `(message, context) => ReactNode` | Optional | Override the header view (sender name area) |
 | `renderFooterView` | `(message, context) => ReactNode` | Optional | Override the footer view (reactions area) |
@@ -60,7 +60,7 @@
 
 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 @@
   → ImagePlugin.renderBubble() is called
 ```
 
+<Note>
+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.
+</Note>
+
 ---
 
 ## 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";
@@ -97,8 +101,8 @@
 | Plugin | Message type(s) | Category | What it renders | Component |
 | --- | --- | --- | --- | --- |
 | **Text** | `text` | `message` | Formatted text with @mentions, clickable URLs, and markdown | [Text Bubble](/ui-kit/react/components/text-bubble) |
 | **Image** | `image` | `message` | Responsive image grid with captions, batch grouping, and a fullscreen gallery | [Image Bubble](/ui-kit/react/components/image-bubble) |
 | **Video** | `video` | `message` | Video grid with poster thumbnails, duration overlays, and a fullscreen viewer | [Video Bubble](/ui-kit/react/components/video-bubble) |
 | **File** | `file` | `message` | Stacked file cards with type icons, size, and download | [File Bubble](/ui-kit/react/components/file-bubble) |
 | **Audio** | `audio` | `message` | Attached audio as stacked player cards; recorded voice notes as a waveform player | [Audio Bubble](/ui-kit/react/components/audio-bubble) |
 | **Polls** | `extension_poll` | `custom` | Interactive poll with voting and live results | [Poll Bubble](/ui-kit/react/components/poll-bubble) |
@@ -138,9 +142,9 @@
 | `toolArguments` | "Tool call" |
 | `toolResults` | "Tool result" |
 
 ### Preloading
 
 The AI Assistant Chat panel can be preloaded on hover/focus to reduce perceived latency:
 
 ```tsx
 import { preloadAIAssistantChat } from "@cometchat/chat-uikit-react";

ui-kit/react/plugins/text-formatters.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Text Formatters"
 sidebarTitle: "Text Formatters"
 description: "Transform plain text into formatted HTML in message bubbles, with built-in URL, mention, and markdown formatters plus custom formatters."
 ---
 
 Text formatters detect patterns in message text and transform them into formatted HTML for display in bubbles. They run as a pipeline — each formatter receives the output of the previous one, sorted by priority (lower number = runs first). The Text plugin provides three built-in formatters, and you can add your own.
 
 ## Built-in Formatters
 
 | Formatter | Priority | Detects | Output |
 | --- | --- | --- | --- |
@@ -26,7 +26,7 @@
 
 ## The Formatter Interface
 
 All formatters extend the abstract `CometChatTextFormatter` class:
 
 ```typescript
 abstract class CometChatTextFormatter {
@@ -99,9 +99,9 @@
 }
 ```
 
 ## Registering Custom Formatters
 
 Custom formatters are registered by creating a custom text plugin that provides them:
 
 ```typescript title="src/plugins/CustomTextPlugin.ts"
 import { CometChatTextPlugin } from "@cometchat/chat-uikit-react";
@@ -139,13 +139,13 @@
 </CometChatProvider>
 ```
 
-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
 
 ### CometChatMarkdownFormatter
 
 Converts markdown syntax to HTML. Runs first (priority 10) so subsequent formatters operate on HTML output.
 
 - `**bold**` → `<b>bold</b>`
 - `_italic_` → `<i>italic</i>`
@@ -159,7 +159,7 @@
 
 ### CometChatMentionsFormatter
 
 Resolves SDK mention tokens (`<@uid:xxx>` and `<@all:label>`) into styled mention chips. Requires the mentioned-users list from the message to resolve UIDs to display names.
 
 ### CometChatUrlFormatter
 
@@ -168,7 +168,7 @@
 ## Tips
 
 - **Priority matters** — markdown must run before mentions/URLs so it doesn't break HTML tags
 - **Protect code blocks** — formatters should skip content inside `<code>` and `<pre>` tags
 - **Keep it fast** — formatters run on every text message render; avoid expensive operations
 - **Use `shouldFormat()`** — override to skip formatting for specific messages
 - **Store metadata** — use `this.metadata` to expose extracted data (URLs, hashtags, mentions) to consumers