From 1ab76c252243f4ba18c565bddffcb66fa62cd5e1 Mon Sep 17 00:00:00 2001
From: Matias Perez <matiasperezpc@hotmail.com>
Date: Mon, 29 Dec 2025 03:02:01 -0300
Subject: [PATCH 1/3] feat(mention): add controlled mention demo and update
 documentation

- Introduced a new demo for controlled mentions, showcasing user interactions with mentions in a chat-like interface.
- Updated the registry to include the new demo and its dependencies.
- Enhanced documentation to include the new demo under the mentions section, providing users with a clear example of usage.
- Added necessary JSON files for the new demo in the public registry.
---
 docs/__registry__/index.tsx                   |  14 ++
 docs/content/docs/components/mention.mdx      |   4 +
 docs/public/r/mention-controlled-demo.json    |  15 ++
 docs/public/r/registry.json                   |  13 ++
 .../examples/mention-controlled-demo.tsx      | 141 ++++++++++++++++++
 docs/registry/registry-examples.ts            |  11 ++
 packages/mention/src/mention-highlighter.tsx  |  21 ++-
 packages/mention/src/mention-input.tsx        |  66 ++++++--
 8 files changed, 264 insertions(+), 21 deletions(-)
 create mode 100644 docs/public/r/mention-controlled-demo.json
 create mode 100644 docs/registry/default/examples/mention-controlled-demo.tsx

diff --git a/docs/__registry__/index.tsx b/docs/__registry__/index.tsx
index 8a11d479e..0c211a6d5 100644
--- a/docs/__registry__/index.tsx
+++ b/docs/__registry__/index.tsx
@@ -2239,6 +2239,20 @@ export const Index: Record<string, any> = {
       source: "",
       chunks: []
     },
+    "mention-controlled-demo": {
+      name: "mention-controlled-demo",
+      description: "",
+      type: "registry:example",
+      registryDependencies: undefined,
+      files: [{
+        path: "registry/default/examples/mention-controlled-demo.tsx",
+        type: "registry:example",
+        target: ""
+      }],
+      component: React.lazy(() => import("@/registry/default/examples/mention-controlled-demo.tsx")),
+      source: "",
+      chunks: []
+    },
     "mention-custom-filter-demo": {
       name: "mention-custom-filter-demo",
       description: "",
diff --git a/docs/content/docs/components/mention.mdx b/docs/content/docs/components/mention.mdx
index 35b90f830..73ff3ecd5 100644
--- a/docs/content/docs/components/mention.mdx
+++ b/docs/content/docs/components/mention.mdx
@@ -76,6 +76,10 @@ return (
 
 <ComponentTabs name="mention-custom-filter-demo" />
 
+### Controlled
+
+<ComponentTabs name="mention-controlled-demo" />
+
 ## API Reference
 
 ### Mention
diff --git a/docs/public/r/mention-controlled-demo.json b/docs/public/r/mention-controlled-demo.json
new file mode 100644
index 000000000..cc5225035
--- /dev/null
+++ b/docs/public/r/mention-controlled-demo.json
@@ -0,0 +1,15 @@
+{
+  "name": "mention-controlled-demo",
+  "dependencies": [
+    "@diceui/mention"
+  ],
+  "files": [
+    {
+      "path": "examples/mention-controlled-demo.tsx",
+      "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { Button } from \"@/components/ui/button\";\nimport { Textarea } from \"@/components/ui/textarea\";\nimport {\n  Mention,\n  MentionContent,\n  MentionInput,\n  MentionItem,\n} from \"@/registry/default/ui/mention\";\n\nconst users = [\n  {\n    id: \"1\",\n    name: \"Olivia Martin\",\n    email: \"olivia@email.com\",\n  },\n  {\n    id: \"2\",\n    name: \"Isabella Nguyen\",\n    email: \"isabella@email.com\",\n  },\n  {\n    id: \"3\",\n    name: \"Emma Wilson\",\n    email: \"emma@email.com\",\n  },\n  {\n    id: \"4\",\n    name: \"Jackson Lee\",\n    email: \"jackson@email.com\",\n  },\n  {\n    id: \"5\",\n    name: \"William Kim\",\n    email: \"will@email.com\",\n  },\n];\n\ninterface Message {\n  id: string;\n  content: string;\n  mentions: string[];\n}\n\nfunction renderMessageContent(content: string, mentions: string[]) {\n  if (mentions.length === 0) return content;\n\n  const escaped = mentions.map((n) => n.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\"));\n  const pattern = new RegExp(`(@(?:${escaped.join(\"|\")}))`, \"g\");\n\n  return content.split(pattern).map((part, i) =>\n    part.startsWith(\"@\") && mentions.includes(part.slice(1)) ? (\n      <span\n        key={i}\n        className=\"rounded bg-blue-200 py-px text-blue-950 dark:bg-blue-800 dark:text-blue-50\"\n      >\n        {part}\n      </span>\n    ) : (\n      part\n    )\n  );\n}\n\nexport default function MentionControlledDemo() {\n  const [open, setOpen] = React.useState(false);\n  const [value, setValue] = React.useState<string[]>([]);\n  const [inputValue, setInputValue] = React.useState(\"\");\n  const [messages, setMessages] = React.useState<Message[]>([]);\n\n  function onSend() {\n    if (!inputValue.trim()) return;\n\n    setMessages((prev) => [\n      ...prev,\n      {\n        id: crypto.randomUUID(),\n        content: inputValue,\n        mentions: value,\n      },\n    ]);\n    setInputValue(\"\");\n    setValue([]);\n  }\n\n  return (\n    <div className=\"grid h-full w-full max-w-[400px] grid-rows-[1fr_auto_1fr] gap-3\">\n      <div className=\"relative flex flex-col justify-end overflow-y-hidden\">\n        <div className=\"pointer-events-none absolute inset-x-0 top-0 z-10 h-12 bg-linear-to-b from-white to-transparent dark:from-fd-background\" />\n        {messages.length > 0 && (\n          <div className=\"flex flex-col gap-2\">\n            {messages.map((message) => (\n              <div\n                key={message.id}\n                className=\"rounded-md border border-zinc-200 bg-zinc-50 p-3 text-sm dark:border-zinc-800 dark:bg-zinc-900\"\n              >\n                <p className=\"whitespace-pre-wrap text-zinc-900 dark:text-zinc-100\">\n                  {renderMessageContent(message.content, message.mentions)}\n                </p>\n              </div>\n            ))}\n          </div>\n        )}\n      </div>\n      <div className=\"flex flex-col gap-3\">\n        <Mention\n          open={open}\n          onOpenChange={setOpen}\n          value={value}\n          onValueChange={setValue}\n          inputValue={inputValue}\n          onInputValueChange={setInputValue}\n        >\n          <MentionInput placeholder=\"Type @ to mention someone...\" asChild>\n            <Textarea />\n          </MentionInput>\n          <MentionContent>\n            {users.map((user) => (\n              <MentionItem\n                key={user.id}\n                value={user.name}\n                className=\"flex-col items-start gap-0.5\"\n              >\n                <span className=\"text-sm\">{user.name}</span>\n                <span className=\"text-muted-foreground text-xs\">\n                  {user.email}\n                </span>\n              </MentionItem>\n            ))}\n          </MentionContent>\n        </Mention>\n        <Button onClick={onSend} disabled={!inputValue.trim()}>\n          Send\n        </Button>\n      </div>\n      <div />\n    </div>\n  );\n}\n",
+      "type": "registry:example",
+      "target": ""
+    }
+  ],
+  "type": "registry:example"
+}
\ No newline at end of file
diff --git a/docs/public/r/registry.json b/docs/public/r/registry.json
index ca7d56f04..ee5d6e1de 100644
--- a/docs/public/r/registry.json
+++ b/docs/public/r/registry.json
@@ -2583,6 +2583,19 @@
       ],
       "type": "registry:example"
     },
+    {
+      "name": "mention-controlled-demo",
+      "dependencies": [
+        "@diceui/mention"
+      ],
+      "files": [
+        {
+          "path": "examples/mention-controlled-demo.tsx",
+          "type": "registry:example"
+        }
+      ],
+      "type": "registry:example"
+    },
     {
       "name": "mention-custom-filter-demo",
       "dependencies": [
diff --git a/docs/registry/default/examples/mention-controlled-demo.tsx b/docs/registry/default/examples/mention-controlled-demo.tsx
new file mode 100644
index 000000000..77f3332e8
--- /dev/null
+++ b/docs/registry/default/examples/mention-controlled-demo.tsx
@@ -0,0 +1,141 @@
+"use client";
+
+import * as React from "react";
+import { Button } from "@/components/ui/button";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  Mention,
+  MentionContent,
+  MentionInput,
+  MentionItem,
+} from "@/registry/default/ui/mention";
+
+const users = [
+  {
+    id: "1",
+    name: "Olivia Martin",
+    email: "olivia@email.com",
+  },
+  {
+    id: "2",
+    name: "Isabella Nguyen",
+    email: "isabella@email.com",
+  },
+  {
+    id: "3",
+    name: "Emma Wilson",
+    email: "emma@email.com",
+  },
+  {
+    id: "4",
+    name: "Jackson Lee",
+    email: "jackson@email.com",
+  },
+  {
+    id: "5",
+    name: "William Kim",
+    email: "will@email.com",
+  },
+];
+
+interface Message {
+  id: string;
+  content: string;
+  mentions: string[];
+}
+
+function renderMessageContent(content: string, mentions: string[]) {
+  if (mentions.length === 0) return content;
+
+  const escaped = mentions.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  const pattern = new RegExp(`(@(?:${escaped.join("|")}))`, "g");
+
+  return content.split(pattern).map((part, i) =>
+    part.startsWith("@") && mentions.includes(part.slice(1)) ? (
+      <span
+        key={i}
+        className="rounded bg-blue-200 py-px text-blue-950 dark:bg-blue-800 dark:text-blue-50"
+      >
+        {part}
+      </span>
+    ) : (
+      part
+    )
+  );
+}
+
+export default function MentionControlledDemo() {
+  const [open, setOpen] = React.useState(false);
+  const [value, setValue] = React.useState<string[]>([]);
+  const [inputValue, setInputValue] = React.useState("");
+  const [messages, setMessages] = React.useState<Message[]>([]);
+
+  function onSend() {
+    if (!inputValue.trim()) return;
+
+    setMessages((prev) => [
+      ...prev,
+      {
+        id: crypto.randomUUID(),
+        content: inputValue,
+        mentions: value,
+      },
+    ]);
+    setInputValue("");
+    setValue([]);
+  }
+
+  return (
+    <div className="grid h-full w-full max-w-[400px] grid-rows-[1fr_auto_1fr] gap-3">
+      <div className="relative flex flex-col justify-end overflow-y-hidden">
+        <div className="pointer-events-none absolute inset-x-0 top-0 z-10 h-12 bg-linear-to-b from-white to-transparent dark:from-fd-background" />
+        {messages.length > 0 && (
+          <div className="flex flex-col gap-2">
+            {messages.map((message) => (
+              <div
+                key={message.id}
+                className="rounded-md border border-zinc-200 bg-zinc-50 p-3 text-sm dark:border-zinc-800 dark:bg-zinc-900"
+              >
+                <p className="whitespace-pre-wrap text-zinc-900 dark:text-zinc-100">
+                  {renderMessageContent(message.content, message.mentions)}
+                </p>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+      <div className="flex flex-col gap-3">
+        <Mention
+          open={open}
+          onOpenChange={setOpen}
+          value={value}
+          onValueChange={setValue}
+          inputValue={inputValue}
+          onInputValueChange={setInputValue}
+        >
+          <MentionInput placeholder="Type @ to mention someone..." asChild>
+            <Textarea />
+          </MentionInput>
+          <MentionContent>
+            {users.map((user) => (
+              <MentionItem
+                key={user.id}
+                value={user.name}
+                className="flex-col items-start gap-0.5"
+              >
+                <span className="text-sm">{user.name}</span>
+                <span className="text-muted-foreground text-xs">
+                  {user.email}
+                </span>
+              </MentionItem>
+            ))}
+          </MentionContent>
+        </Mention>
+        <Button onClick={onSend} disabled={!inputValue.trim()}>
+          Send
+        </Button>
+      </div>
+      <div />
+    </div>
+  );
+}
diff --git a/docs/registry/registry-examples.ts b/docs/registry/registry-examples.ts
index 5c91b66b0..1e7964222 100644
--- a/docs/registry/registry-examples.ts
+++ b/docs/registry/registry-examples.ts
@@ -1251,6 +1251,17 @@ export const examples: Registry["items"] = [
       },
     ],
   },
+  {
+    name: "mention-controlled-demo",
+    type: "registry:example",
+    dependencies: ["@diceui/mention"],
+    files: [
+      {
+        path: "examples/mention-controlled-demo.tsx",
+        type: "registry:example",
+      },
+    ],
+  },
   {
     name: "mention-custom-filter-demo",
     type: "registry:example",
diff --git a/packages/mention/src/mention-highlighter.tsx b/packages/mention/src/mention-highlighter.tsx
index 88170d816..5266348d1 100644
--- a/packages/mention/src/mention-highlighter.tsx
+++ b/packages/mention/src/mention-highlighter.tsx
@@ -130,14 +130,25 @@ const MentionHighlighter = React.memo(
       }, [inputStyle, style, context.dir]);
 
       const onSegmentsRender = React.useCallback(() => {
-        const inputElement = context.inputRef.current;
-        if (!inputElement) return null;
+        const value = context.inputValue;
+
+        // Return early if there's no value
+        if (!value) {
+          return <span key="space">&nbsp;</span>;
+        }
 
-        const { value } = inputElement;
         const segments: React.ReactNode[] = [];
         let lastIndex = 0;
 
-        for (const { start, end } of context.mentions) {
+        // Filter out mentions with invalid positions
+        const validMentions = context.mentions.filter(
+          (mention) =>
+            mention.start >= 0 &&
+            mention.end <= value.length &&
+            mention.start < mention.end
+        );
+
+        for (const { start, end } of validMentions) {
           // Add text before mention
           if (start > lastIndex) {
             segments.push(
@@ -170,7 +181,7 @@ const MentionHighlighter = React.memo(
         segments.push(<span key="space">&nbsp;</span>);
 
         return segments;
-      }, [context.inputRef, context.mentions]);
+      }, [context.inputValue, context.mentions]);
 
       if (!inputStyle) return null;
 
diff --git a/packages/mention/src/mention-input.tsx b/packages/mention/src/mention-input.tsx
index 0429c9f24..a97fae39b 100644
--- a/packages/mention/src/mention-input.tsx
+++ b/packages/mention/src/mention-input.tsx
@@ -22,6 +22,17 @@ const MentionInput = React.forwardRef<InputElement, MentionInputProps>(
     const context = useMentionContext(INPUT_NAME);
     const composedRef = useComposedRefs(forwardedRef, context.inputRef);
 
+    // Sync controlled inputValue to the actual input element
+    React.useEffect(() => {
+      const inputElement = context.inputRef.current;
+      if (!inputElement) return;
+
+      // Only sync if the values differ (avoid unnecessary DOM updates)
+      if (inputElement.value !== context.inputValue) {
+        inputElement.value = context.inputValue;
+      }
+    }, [context.inputValue, context.inputRef]);
+
     const getTextWidth = React.useCallback(
       (text: string, input: InputElement) => {
         const style = window.getComputedStyle(input);
@@ -272,24 +283,45 @@ const MentionInput = React.forwardRef<InputElement, MentionInputProps>(
         const prevValue = context.inputValue;
         const insertedLength = newValue.length - prevValue.length;
 
+        // Clear all mentions if input is completely cleared
+        if (newValue === "") {
+          if (context.mentions.length > 0) {
+            context.onMentionsChange([]);
+            context.onValueChange?.([]);
+          }
+          context.onInputValueChange?.(newValue);
+          onMentionUpdate(input);
+          return;
+        }
+
         // Update mentions positions based on text changes
         if (insertedLength !== 0) {
-          context.onMentionsChange((prev) =>
-            prev.map((mention) => {
-              // Only update positions for mentions that come after the cursor
-              if (
-                mention.start >=
-                cursorPosition - (insertedLength > 0 ? insertedLength : 0)
-              ) {
-                return {
-                  ...mention,
-                  start: mention.start + insertedLength,
-                  end: mention.end + insertedLength,
-                };
-              }
-              return mention;
-            }),
-          );
+          context.onMentionsChange((prev) => {
+            const updated = prev
+              .map((mention) => {
+                // Only update positions for mentions that come after the cursor
+                if (
+                  mention.start >=
+                  cursorPosition - (insertedLength > 0 ? insertedLength : 0)
+                ) {
+                  return {
+                    ...mention,
+                    start: mention.start + insertedLength,
+                    end: mention.end + insertedLength,
+                  };
+                }
+                return mention;
+              })
+              // Filter out mentions with invalid positions
+              .filter(
+                (mention) =>
+                  mention.start >= 0 &&
+                  mention.end <= newValue.length &&
+                  mention.start < mention.end,
+              );
+
+            return updated;
+          });
         }
 
         context.onInputValueChange?.(newValue);
@@ -299,6 +331,8 @@ const MentionInput = React.forwardRef<InputElement, MentionInputProps>(
         context.onInputValueChange,
         context.inputValue,
         context.onMentionsChange,
+        context.onValueChange,
+        context.mentions.length,
         onMentionUpdate,
         context.disabled,
         context.readonly,

From fea16ffaf64023a75a18abdf8d1813cd6b81afea Mon Sep 17 00:00:00 2001
From: Matias Perez <matiasperezpc@hotmail.com>
Date: Mon, 29 Dec 2025 03:25:24 -0300
Subject: [PATCH 2/3] undo some stuff

---
 packages/mention/src/mention-input.tsx | 54 ++++++++------------------
 1 file changed, 16 insertions(+), 38 deletions(-)

diff --git a/packages/mention/src/mention-input.tsx b/packages/mention/src/mention-input.tsx
index a97fae39b..af2ffee57 100644
--- a/packages/mention/src/mention-input.tsx
+++ b/packages/mention/src/mention-input.tsx
@@ -283,45 +283,24 @@ const MentionInput = React.forwardRef<InputElement, MentionInputProps>(
         const prevValue = context.inputValue;
         const insertedLength = newValue.length - prevValue.length;
 
-        // Clear all mentions if input is completely cleared
-        if (newValue === "") {
-          if (context.mentions.length > 0) {
-            context.onMentionsChange([]);
-            context.onValueChange?.([]);
-          }
-          context.onInputValueChange?.(newValue);
-          onMentionUpdate(input);
-          return;
-        }
-
         // Update mentions positions based on text changes
         if (insertedLength !== 0) {
-          context.onMentionsChange((prev) => {
-            const updated = prev
-              .map((mention) => {
-                // Only update positions for mentions that come after the cursor
-                if (
-                  mention.start >=
-                  cursorPosition - (insertedLength > 0 ? insertedLength : 0)
-                ) {
-                  return {
-                    ...mention,
-                    start: mention.start + insertedLength,
-                    end: mention.end + insertedLength,
-                  };
-                }
-                return mention;
-              })
-              // Filter out mentions with invalid positions
-              .filter(
-                (mention) =>
-                  mention.start >= 0 &&
-                  mention.end <= newValue.length &&
-                  mention.start < mention.end,
-              );
-
-            return updated;
-          });
+          context.onMentionsChange((prev) =>
+            prev.map((mention) => {
+              // Only update positions for mentions that come after the cursor
+              if (
+                mention.start >=
+                cursorPosition - (insertedLength > 0 ? insertedLength : 0)
+              ) {
+                return {
+                  ...mention,
+                  start: mention.start + insertedLength,
+                  end: mention.end + insertedLength,
+                };
+              }
+              return mention;
+            }),
+          );
         }
 
         context.onInputValueChange?.(newValue);
@@ -332,7 +311,6 @@ const MentionInput = React.forwardRef<InputElement, MentionInputProps>(
         context.inputValue,
         context.onMentionsChange,
         context.onValueChange,
-        context.mentions.length,
         onMentionUpdate,
         context.disabled,
         context.readonly,

From 2d4ed2e9e4a9548a8d81687152692bc75848b982 Mon Sep 17 00:00:00 2001
From: Matias Perez <matiasperezpc@hotmail.com>
Date: Mon, 29 Dec 2025 03:28:59 -0300
Subject: [PATCH 3/3] remove early return

---
 packages/mention/src/mention-highlighter.tsx | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/packages/mention/src/mention-highlighter.tsx b/packages/mention/src/mention-highlighter.tsx
index 5266348d1..34b577c16 100644
--- a/packages/mention/src/mention-highlighter.tsx
+++ b/packages/mention/src/mention-highlighter.tsx
@@ -132,11 +132,6 @@ const MentionHighlighter = React.memo(
       const onSegmentsRender = React.useCallback(() => {
         const value = context.inputValue;
 
-        // Return early if there's no value
-        if (!value) {
-          return <span key="space">&nbsp;</span>;
-        }
-
         const segments: React.ReactNode[] = [];
         let lastIndex = 0;