React Mentions

https://github.com/hbmartin/react-mentions-ts
Admin
A React component that enables Facebook/Twitter-style @mentions and tagging in textarea inputs with...
Tokens:116,398
Snippets:811
Trust Score:9.6
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install react-mentions-ts with npm, yarn, or pnpm

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/getting-started.md

Install the package using your preferred package manager. The --save flag is used with npm.

```bash
# npm
npm install react-mentions-ts --save

# yarn
yarn add react-mentions-ts

# pnpm
pnpm add react-mentions-ts
```

--------------------------------

### Basic getSubstringIndex usage examples

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/_autodocs/api-reference/getSubstringIndex.md

Basic usage examples showing default case-insensitive matching, case-sensitive matching when caseInsensitive is true, accent-insensitive matching with ignoreAccents, and non-matching behavior. The comments show the expected return values.

```ts
import getSubstringIndex from 'react-mentions-ts'

getSubstringIndex('Hello world', 'WORLD') // → 6 (case-insensitive by default)
getSubstringIndex('Hello world', 'world', false, true) // → -1 (case-sensitive)

// Accent-insensitive lookup on the original string:
getSubstringIndex('José & José', 'Jose', true) // → 0
getSubstringIndex('Lydìã', 'Lydia', true) // → 0

// Non-matching:
getSubstringIndex('abc', 'z') // → -1
```

--------------------------------

### flatMap examples for emails and numbers

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-flatmap-filter.md

Two additional examples: extracting valid emails from responses and parsing/filtering valid numbers, each showing the before (map/filter) and after (flatMap) versions.

```typescript
// Extract valid emails from responses
// Before
const emails = responses
  .map((r) => (r.success ? r.data.email : null))
  .filter((email) => email != null)

// After
const emails = responses.flatMap((r) => (r.success ? [r.data.email] : []))
```

```typescript
// Parse and filter valid numbers
// Before
const numbers = strings.map((s) => parseInt(s, 10)).filter((n) => !isNaN(n))

// After
const numbers = strings.flatMap((s) => {
  const n = parseInt(s, 10)
  return isNaN(n) ? [] : [n]
})
```

--------------------------------

### Rendered mention HTML example

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/_autodocs/api-reference/MentionsText.md

Shows the default HTML output for a mention, with data-mention-id and mentionClassName.

```html
<strong data-mention-id="walter" class="mentionClassName">Walter White</strong>
```

--------------------------------

### Markup format example

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/advanced.md

Example of a value string in the default markup format. The __display__ placeholder stores the visible text and __id__ stores the mention identifier. When rendered, the user sees plain text while the underlying value preserves the structured mention data.

```text
Hey @[Walter White](walter), are you there?
```

--------------------------------

### Tailwind CSS setup for react-mentions-ts

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/styling.md

Minimal Tailwind setup for the consuming app. The CSS import includes the optional helper file that declares an `@source "../dist";` directive so Tailwind v4 can detect the library's utility classes inside `node_modules/react-mentions-ts/dist`. For Tailwind v3, add `./node_modules/react-mentions-ts/dist/**/*.{js,jsx,ts,tsx}` to the `content` array instead of importing the helper file.

```javascript
// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: { extend: {} },
  plugins: [],
}
```

```css
/* src/index.css (or your global stylesheet) */
@import 'tailwindcss';
@import 'react-mentions-ts/styles/tailwind.css';
```

--------------------------------

### Correct: Parallelize API Route with Promise.all

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/async-api-routes.md

Correct pattern: starts auth() and fetchConfig() immediately, then awaits session and uses Promise.all to run fetchData() in parallel with configPromise.

```typescript
export async function GET(request: Request) {
  const sessionPromise = auth()
  const configPromise = fetchConfig()
  const session = await sessionPromise
  const [config, data] = await Promise.all([configPromise, fetchData(session.user.id)])
  return Response.json({ data, config })
}
```

--------------------------------

### React example: incorrect vs correct

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-batch-dom-css.md

React example showing the incorrect pattern of interleaving style changes with layout queries in a useEffect, and the correct pattern of toggling a CSS class based on a prop. The correct version avoids forced layouts entirely.

```tsx
// Incorrect: interleaving style changes with layout queries
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  const ref = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (ref.current && isHighlighted) {
      ref.current.style.width = '100px'
      const width = ref.current.offsetWidth // Forces layout
      ref.current.style.height = '200px'
    }
  }, [isHighlighted])

  return <div ref={ref}>Content</div>
}

// Correct: toggle class
function Box({ isHighlighted }: { isHighlighted: boolean }) {
  return <div className={isHighlighted ? 'highlighted-box' : ''}>Content</div>
}
```

--------------------------------

### Alternative: Promise chaining with Promise.all

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/async-dependencies.md

This example shows an alternative approach without extra dependencies. It creates the promises first, chains `fetchProfile` on the user promise, and then uses `Promise.all` to await all three promises concurrently.

```typescript
const userPromise = fetchUser()
const profilePromise = userPromise.then((user) => fetchProfile(user.id))

const [user, config, profile] = await Promise.all([userPromise, fetchConfig(), profilePromise])
```

--------------------------------

### Update package and imports from react-mentions to react-mentions-ts

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/migration.md

Shows the diff for installing the new package and updating the import statement. Use this when starting the migration.

```diff
- npm install react-mentions
+ npm install react-mentions-ts

- import { MentionsInput, Mention } from 'react-mentions'
+ import { MentionsInput, Mention } from 'react-mentions-ts'
```

--------------------------------

### Install peer dependencies for react-mentions-ts

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/getting-started.md

Install required peer dependencies. react and react-dom are always required; class-variance-authority, clsx, and tailwind-merge are only needed if using the built-in Tailwind styling.

```bash
# Required
npm install react react-dom

# Required only if using the built-in Tailwind utility classes
npm install class-variance-authority clsx tailwind-merge
```

--------------------------------

### Correct: Using better-all for parallel execution

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/async-dependencies.md

This example uses `better-all`'s `all` function to run `fetchUser`, `fetchConfig`, and `fetchProfile` concurrently. The `profile` task accesses the user via `this.$.user` after it resolves, allowing `config` and `profile` to run in parallel.

```typescript
import { all } from 'better-all'

const { user, config, profile } = await all({
  async user() {
    return fetchUser()
  },
  async config() {
    return fetchConfig()
  },
  async profile() {
    return fetchProfile((await this.$.user).id)
  },
})
```

--------------------------------

### Incorrect: Manual loading state in SearchResults

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rendering-usetransition-loading.md

Manual loading state example that sets isLoading before and after the async fetch. This approach is marked as incorrect because it does not use useTransition for the result update.

```tsx
function SearchResults() {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])
  const [isLoading, setIsLoading] = useState(false)

  const handleSearch = async (value: string) => {
    setIsLoading(true)
    setQuery(value)
    const data = await fetchResults(value)
    setResults(data)
    setIsLoading(false)
  }

  return (
    <>
      <input value={query} onChange={(e) => handleSearch(e.target.value)} />
      {isLoading && <Spinner />}
      <ResultsList results={results} />
    </>
  )
}
```

--------------------------------

### Correct: ScrollTracker with startTransition (non-blocking)

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rerender-transitions.md

This example wraps the scroll state update in startTransition, making it non-blocking and maintaining UI responsiveness. It requires importing startTransition from 'react'.

```tsx
import { startTransition } from 'react'

function ScrollTracker() {
  const [scrollY, setScrollY] = useState(0)
  useEffect(() => {
    const handler = () => {
      startTransition(() => setScrollY(window.scrollY))
    }
    window.addEventListener('scroll', handler, { passive: true })
    return () => window.removeEventListener('scroll', handler)
  }, [])
}
```

--------------------------------

### Imperative API example with useRef and insertText

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/README.md

Attach a ref to MentionsInput to programmatically insert text at the current caret position or replace the current selection. The example shows a button that calls insertText('anything') on the ref. Requires the MentionsInputHandle type and the useRef hook.

```tsx
import { useRef, useState } from 'react'
import { Mention, MentionsInput, type MentionsInputHandle } from 'react-mentions-ts'

const users = [
  { id: 'walter', display: 'Walter White' },
  { id: 'jesse', display: 'Jesse Pinkman' },
]

function ImperativeApiExample() {
  const mentionsRef = useRef<MentionsInputHandle>(null)
  const [value, setValue] = useState('')

  const handleInsertText = () => {
    mentionsRef.current?.insertText('anything')
  }

  return (
    <>
      <button type="button" onClick={handleInsertText}>
        Insert text
      </button>

      <MentionsInput
        ref={mentionsRef}
        value={value}
        onMentionsChange={({ value: nextValue }) => setValue(nextValue)}
      >
        <Mention trigger="@" data={users} />
      </MentionsInput>
    </>
  )
}
```

--------------------------------

### Usage: Composing the compound component

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/architecture-compound-components.md

Usage example showing how consumers explicitly compose exactly the pieces they need, with no hidden conditionals. The provider injects state, actions, and meta, allowing multiple usages of the same component structure.

```tsx
<Composer.Provider state={state} actions={actions} meta={meta}>
  <Composer.Frame>
    <Composer.Header />
    <Composer.Input />
    <Composer.Footer>
      <Composer.Formatting />
      <Composer.Submit />
    </Composer.Footer>
  </Composer.Frame>
</Composer.Provider>
```

--------------------------------

### getSubstringIndex

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/_autodocs/api-reference/getSubstringIndex.md

Documentation for the getSubstringIndex utility function, including its signature, parameters, return type, behavior notes, and usage examples.

```APIDOC
## getSubstringIndex

### Description
Utility for finding the first occurrence of a substring within a haystack with optional accent-insensitive and case-insensitive matching. It is used internally by the array-data suggestion filter and exported for consumers who need the same matching semantics.

### Function Signature
```ts
const getSubstringIndex = (
  haystack: string,
  needle: string,
  ignoreAccents?: boolean,
  caseInsensitive?: boolean
): number => {
  // ...
}
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `haystack` | `string` | required | — | The string to search |
| `needle` | `string` | required | — | The substring to find |
| `ignoreAccents` | `boolean` | optional | `false` | When `true`, both strings are NFD-normalized and combining marks (`\p{M}`) are stripped before matching, so `'Lydìã'` matches a needle of `'Lydia'` |
| `caseInsensitive` | `boolean` | optional | `true` | When `false`, comparison is exact/case-sensitive instead of `toLowerCase`-based |

### Return Type
Returns `number` — the UTF-16 code-unit index of the first match in the *original* `haystack`, or `-1` when there is no match.

Important indexing detail: when `ignoreAccents` is `true`, the returned index is mapped back through the normalization offset map, so the result is always a valid index into the untransformed `haystack` (surrogate pairs/emojis stay aligned because the mapping tracks UTF-16 code units, not code points).

### Behavior Notes
- Matching is always case-insensitive by default: both arguments are run through `toLowerCase()` (or `toLocaleLowerCase`-equivalent via `toLowerCase`) unless `caseInsensitive === false`.
- When `ignoreAccents` is not `true`, the plain path is a direct `indexOf`:
  - `caseInsensitive === false` → `haystack.indexOf(needle)`
  - otherwise → `haystack.toLowerCase().indexOf(needle.toLowerCase())`
- The accent-stripping path iterates the haystack by code point, NFD-normalizes each character, removes combining marks with the `\p{M}` Unicode property, and records for each produced UTF-16 code unit the original position `i`.
- Invalid/corrupt surrogate halves are skipped defensively (`codePointAt` returning `undefined` advances `i`).

### Examples
```ts
import getSubstringIndex from 'react-mentions-ts'

getSubstringIndex('Hello world', 'WORLD') // → 6 (case-insensitive by default)
getSubstringIndex('Hello world', 'world', false, true) // → -1 (case-sensitive)

// Accent-insensitive lookup on the original string:
getSubstringIndex('José & José', 'Jose', true) // → 0
getSubstringIndex('Lydìã', 'Lydia', true) // → 0

// Non-matching:
getSubstringIndex('abc', 'z') // → -1
```

### Realistic usage — filter suggestions with the same semantics as `MentionsInput`
```ts
import getSubstringIndex from 'react-mentions-ts'

const items = [{ id: 'jose', display: 'José' }, { id: 'jon', display: 'Jon' }]

const matches = items.filter((item) => getSubstringIndex(item.display, 'jose', true) >= 0)
// → [{ id: 'jose', display: 'José' }]
```

### Notes
- This function has no throwing error paths — it always returns `number`.
- It is the exact function injected into the internal data provider (`getDataProvider` receives `getSubstringIndex` in its options) so highlighting offsets produced by array filtering match the positions this function returns.
```

--------------------------------

### Error handling: template with no placeholders

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/_autodocs/api-reference/createMarkupSerializer.md

Error handling example showing that createMarkupSerializer throws an Error when the template lacks both __id__ and __display__ placeholders. The error message is shown in the comment.

```ts
import { createMarkupSerializer } from 'react-mentions-ts'

try {
  createMarkupSerializer('@[__display__]') // missing __id__
} catch (error) {
  console.error(error)
  // Error: The markup '@[__display__]' does not contain either of the placeholders '__id__' or '__display__'
}
```

--------------------------------

### Incorrect: Promise.all with unnecessary wait

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/async-dependencies.md

This example shows a common mistake where `fetchProfile` waits for both `fetchUser` and `fetchConfig` to complete, even though it only depends on the user. This reduces parallelism.

```typescript
const [user, config] = await Promise.all([fetchUser(), fetchConfig()])
const profile = await fetchProfile(user.id)
```

--------------------------------

### Incorrect: ScrollTracker without startTransition (blocks UI)

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rerender-transitions.md

This example shows a scroll handler that directly updates state on every scroll event, which can block the UI. Use this as a contrast to the corrected version that uses startTransition.

```tsx
function ScrollTracker() {
  const [scrollY, setScrollY] = useState(0)
  useEffect(() => {
    const handler = () => setScrollY(window.scrollY)
    window.addEventListener('scroll', handler, { passive: true })
    return () => window.removeEventListener('scroll', handler)
  }, [])
}
```

--------------------------------

### Custom serializer for IDs containing )

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/README.md

Example of a custom serializer that percent-encodes reserved characters in mention IDs to safely store them in markup.

```APIDOC
## Custom serializer for IDs containing )

### Description
If your mention IDs can contain characters that would otherwise terminate a template placeholder early, write a custom serializer and encode the `id` before storing it in the markup.

### Example
```ts
import type { MentionSerializer } from 'react-mentions-ts'

const encodeMentionId = (id: string): string =>
  encodeURIComponent(id).replace(
    /[!'()*]/g,
    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`
  )

const decodeMentionId = (encoded: string): string => decodeURIComponent(encoded)

export const parenSafeSerializer: MentionSerializer = {
  id: 'paren-safe-serializer',
  insert: ({ id, display }) => `@[${display}](${encodeMentionId(String(id))})`,
  findAll: (value) => {
    const regex = /@\[([^\]]+)]\(([^)]+)\)/g
    const matches = []
    let match: RegExpExecArray | null

    while ((match = regex.exec(value)) !== null) {
      matches.push({
        markup: match[0],
        index: match.index,
        display: match[1],
        id: decodeMentionId(match[2]),
      })
    }

    return matches
  },
}
```

### Usage
```tsx
<Mention trigger="@" data={users} markup={parenSafeSerializer} />
```

For example, selecting a mention with `id: 'team)west'` stores `@[Team West](team%29west)` in `value`, and `findAll` decodes it back to `team)west`.
```

--------------------------------

### Async data loading with fetch and AbortSignal

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/configuration.md

Pass an async function as the `data` prop to fetch suggestions. The function receives the current query and a `MentionSearchContext` with an `AbortSignal`; the previous request is aborted when the user keeps typing. The example shows a `fetchUsers` function that fetches from `/api/users` and returns a promise of `User[]`.

```tsx
import type { MentionSearchContext } from 'react-mentions-ts'

type User = { id: string; display: string }

const fetchUsers = async (query: string, { signal }: MentionSearchContext): Promise<User[]> => {
  const response = await fetch(`/api/users?search=${query}`, { signal })
  return response.json()
}

;<Mention trigger="@" data={fetchUsers} debounceMs={150} maxSuggestions={8} />
```

--------------------------------

### Incorrect: Script tags without defer or async (blocks rendering)

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rendering-script-defer-async.md

This example shows script tags without defer or async, which block HTML parsing and delay First Contentful Paint and Time to Interactive. Avoid this pattern.

```tsx
export default function Document() {
  return (
    <html>
      <head>
        <script src="https://example.com/analytics.js" />
        <script src="/scripts/utils.js" />
      </head>
      <body>{/* content */}</body>
    </html>
  )
}
```

--------------------------------

### Cursor pagination with async data provider

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/configuration.md

Async providers can return cursor pages. The first request receives `reason: 'query'` and `cursor: null`; subsequent requests with `reason: 'page'` and the previous `nextCursor` append items. Pagination stops when `nextCursor` is null/undefined or `hasMore: false`. The example shows a `fetchUsersPage` function that builds query parameters and fetches from `/api/users`.

```tsx
type UserPage = {
  items: User[]
  nextCursor?: string | null
}

const fetchUsersPage = async (
  query: string,
  { cursor, signal }: MentionSearchContext
): Promise<UserPage> => {
  const params = new URLSearchParams({ search: query })
  if (typeof cursor === 'string') {
    params.set('cursor', cursor)
  }

  const response = await fetch(`/api/users?${params.toString()}`, { signal })
  return response.json()
}

;<Mention trigger="@" data={fetchUsersPage} debounceMs={150} />
```

--------------------------------

### Correct: useTransition with built-in pending state

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rendering-usetransition-loading.md

Correct example using useTransition to mark the result update as non-urgent. It keeps separate isFetching state for the network lifecycle and uses isPending to indicate the transition render, improving responsiveness and allowing new transitions to cancel pending ones.

```tsx
import { useTransition, useState } from 'react'

function SearchResults() {
  const [query, setQuery] = useState('')
  const [results, setResults] = useState([])
  const [isFetching, setIsFetching] = useState(false)
  const [isPending, startTransition] = useTransition()

  const handleSearch = async (value: string) => {
    setQuery(value) // Update input immediately

    setIsFetching(true)
    try {
      const data = await fetchResults(value)

      startTransition(() => {
        // Mark the expensive result update as non-urgent
        setResults(data)
      })
    } finally {
      setIsFetching(false)
    }
  }

  return (
    <>
      <input value={query} onChange={(e) => handleSearch(e.target.value)} />
      {(isFetching || isPending) && <Spinner />}
      <ResultsList results={results} />
    </>
  )
}
```

--------------------------------

### makeTriggerRegex usage examples

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/advanced.md

Builds a properly anchored regex from a trigger string. Useful for spaces in queries or accent-insensitive matching. The default matches @query at end of string; allowSpaceInQuery enables multi-word queries; ignoreAccents enables the Unicode u flag.

```ts
import { makeTriggerRegex } from 'react-mentions-ts'

makeTriggerRegex('@')
// default — matches @query at end of string

makeTriggerRegex('@', { allowSpaceInQuery: true })
// allows "@ John Doe" style multi-word queries

makeTriggerRegex('@', { ignoreAccents: true })
// Unicode-aware matching for accented characters
```

--------------------------------

### Filter suggestions with getSubstringIndex

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/_autodocs/api-reference/getSubstringIndex.md

Realistic usage example filtering suggestion items with the same matching semantics as MentionsInput. It uses accent-insensitive matching to find items whose display contains the query.

```ts
import getSubstringIndex from 'react-mentions-ts'

const items = [{ id: 'jose', display: 'José' }, { id: 'jon', display: 'Jon' }]

const matches = items.filter((item) => getSubstringIndex(item.display, 'jose', true) >= 0)
// → [{ id: 'jose', display: 'José' }]
```

--------------------------------

### Configure Git to fetch and display performance notes

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/CONTRIBUTING.md

Run these three git config commands to set up local Git to fetch and display performance notes stored under refs/notes/perf. After this configuration, `git log --notes=perf` and `git show --notes=perf <commit>` will show recorded perf notes locally.

```bash
git config --add remote.origin.fetch +refs/notes/perf:refs/notes/perf
git config --add notes.displayRef refs/notes/perf
git config --add notes.rewriteRef refs/notes/perf
```

--------------------------------

### Incorrect: Waterfall in API Route GET

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/async-api-routes.md

Incorrect pattern: awaits auth() before starting fetchConfig() and fetchData(), causing a waterfall where config waits for auth and data waits for both.

```typescript
export async function GET(request: Request) {
  const session = await auth()
  const config = await fetchConfig()
  const data = await fetchData(session.user.id)
  return Response.json({ data, config })
}
```

--------------------------------

### The same composed UI works with both providers

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/state-context-interface.md

Shows the same Composer UI composed with ForwardMessageProvider and ChannelProvider, demonstrating that the UI is reusable across different state implementations.

```tsx
// Works with ForwardMessageProvider (local state)
<ForwardMessageProvider>
  <Composer.Frame>
    <Composer.Input />
    <Composer.Submit />
  </Composer.Frame>
</ForwardMessageProvider>

// Works with ChannelProvider (global synced state)
<ChannelProvider channelId="abc">
  <Composer.Frame>
    <Composer.Input />
    <Composer.Submit />
  </Composer.Frame>
</ChannelProvider>
```

--------------------------------

### Incorrect: Static import of MonacoEditor

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/bundle-dynamic-imports.md

Bundles MonacoEditor into the main chunk, increasing initial bundle size by ~300KB and hurting TTI and LCP. Use this only as a contrast to the lazy-loaded version.

```tsx
import { MonacoEditor } from './monaco-editor'

function CodePanel({ code }: { code: string }) {
  return <MonacoEditor value={code} />
}
```

--------------------------------

### MentionSerializer interface

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/advanced.md

Interface for custom mention serializers, including properties and a full example for handling IDs with special characters.

```APIDOC
## MentionSerializer interface

### Description
Interface for custom mention serializers. Implement this directly when createMarkupSerializer is not flexible enough.

### Interface Definition
```ts
interface MentionSerializer {
  id: string
  insert: (input: { id: string | number; display: string }) => string
  findAll: (value: string) => MentionSerializerMatch[]
}

interface MentionSerializerMatch {
  markup: string // the full matched substring
  index: number // position in the value string
  id: string // extracted mention identifier
  display?: string | null // extracted display text
}
```

### Properties
- **id** (string) - A unique string identifying this serializer (used internally to distinguish multiple Mention children).
- **insert** (function) - Given a mention's `id` and `display`, returns the markup string to splice into the value.
- **findAll** (function) - Scans a value string and returns every mention match with its position and extracted fields.

### Custom Serializer Example (for IDs containing `)`)
If your mention IDs can contain characters that would otherwise terminate a template placeholder early, write a custom serializer and encode the `id` before storing it in the markup.

```ts
import type { MentionSerializer } from 'react-mentions-ts'

const encodeMentionId = (id: string): string =>
  encodeURIComponent(id).replace(
    /[!'()*]/g,
    (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`
  )

const decodeMentionId = (encoded: string): string => decodeURIComponent(encoded)

export const parenSafeSerializer: MentionSerializer = {
  id: 'paren-safe-serializer',
  insert: ({ id, display }) => `@[${display}](${encodeMentionId(String(id))})`,
  findAll: (value) => {
    const regex = /@\[([^\]]+)]\(([^)]+)\)/g
    const matches = []
    let match: RegExpExecArray | null

    while ((match = regex.exec(value)) !== null) {
      matches.push({
        markup: match[0],
        index: match.index,
        display: match[1],
        id: decodeMentionId(match[2]),
      })
    }

    return matches
  },
}
```

Use it on `Mention` like any other serializer:

```tsx
<Mention trigger="@" data={users} markup={parenSafeSerializer} />
```

For example, selecting a mention with `id: 'team)west'` stores `@[Team West](team%29west)` in `value`, and `findAll` decodes it back to `team)west`.
```

--------------------------------

### Build Index Maps for Repeated Lookups (Incorrect vs Correct)

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-index-maps.md

The first block is the incorrect O(n) per lookup approach using .find(). The second block is the correct O(1) per lookup approach using a Map. Build the map once (O(n)), then all lookups are O(1). For 1000 orders × 1000 users, this reduces 1M ops to 2K ops.

```typescript
function processOrders(orders: Order[], users: User[]) {
  return orders.map((order) => ({
    ...order,
    user: users.find((u) => u.id === order.userId),
  }))
}
```

```typescript
function processOrders(orders: Order[], users: User[]) {
  const userById = new Map(users.map((u) => [u.id, u]))

  return orders.map((order) => ({
    ...order,
    user: userById.get(order.userId),
  }))
}
```

--------------------------------

### Generate tree-shaking report with pnpm tree-shake:report

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/advanced.md

Run this command to generate a repeatable tree-shaking report. It rebuilds dist, runs npx publint --pack npm, requires "sideEffects": false, inspects npm pack --dry-run --json, and bundles small Vite consumer fixtures against dist/index.js. The npm pack check prints the tarball filename, packed size, unpacked size, and file count.

```bash
pnpm tree-shake:report
```

--------------------------------

### Cursor-based Pagination Provider

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/README.md

Shows how to implement an async data provider that supports cursor-based pagination for infinite scrolling in the mention suggestions list.

```APIDOC
## [ASYNC] Paginated data prop function

### Description
Async providers can return cursor pages. The first request receives `reason: 'query'` and `cursor: null`. When the overlay list scrolls near the bottom, the provider is called again with `reason: 'page'` and the previous `nextCursor`; returned `items` are appended to the active suggestions. `null` or `undefined` `nextCursor`, or `hasMore: false`, stops pagination.

### Parameters
- **query** (string) - The current search query.
- **context** (MentionSearchContext) - An object containing `cursor` (string | null) and `signal` (AbortSignal).

### Returns
- **Promise<{ items: Array, nextCursor?: string | null }>** - A promise that resolves with an object containing `items` and optionally `nextCursor`.

### Example
```tsx
type UserPage = {
  items: User[]
  nextCursor?: string | null
}

const fetchUsersPage = async (
  query: string,
  { cursor, signal }: MentionSearchContext
): Promise<UserPage> => {
  const params = new URLSearchParams({ search: query })
  if (typeof cursor === 'string') {
    params.set('cursor', cursor)
  }

  const response = await fetch(`/api/users?${params.toString()}`, { signal })
  return response.json()
}

;<Mention trigger="@" data={fetchUsersPage} debounceMs={150} />
```
```

--------------------------------

### Correct: Single loop with push (1 iteration)

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-combine-iterations.md

This example combines the three filters into a single for-of loop, iterating the array only once. It is marked as correct and more efficient.

```typescript
const admins: User[] = []
const testers: User[] = []
const inactive: User[] = []

for (const user of users) {
  if (user.isAdmin) admins.push(user)
  if (user.isTester) testers.push(user)
  if (!user.isActive) inactive.push(user)
}
```

--------------------------------

### Test mentions with user-event

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/testing.md

Use @testing-library/user-event for realistic event simulation due to internal cursor tracking. This example renders a mentions component and types '@john' into the textbox.

```tsx
import { render } from '@testing-library/react'
import userEvent from '@testing-library/user-event'

test('mentions work correctly', async () => {
  const user = userEvent.setup()
  const { getByRole } = render(<MyMentionsComponent />)

  await user.type(getByRole('textbox'), '@john')
  // assertions...
})
```

--------------------------------

### Alternative: Share promise across components with use()

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/async-suspense-boundaries.md

Alternative for Client Components: use the `use(promise)` approach to share a single promise across multiple components, ensuring only one fetch occurs while the layout renders immediately.

```tsx
function Page() {
  // Start fetch immediately, but don't await
  const dataPromise = fetchData()

  return (
    <div>
      <div>Sidebar</div>
      <div>Header</div>
      <Suspense fallback={<Skeleton />}>
        <DataDisplay dataPromise={dataPromise} />
        <DataSummary dataPromise={dataPromise} />
      </Suspense>
      <div>Footer</div>
    </div>
  )
}

function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise) // Unwraps the promise
  return <div>{data.content}</div>
}

function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
  const data = use(dataPromise) // Reuses the same promise
  return <div>{data.summary}</div>
}
```

--------------------------------

### Incorrect: Mutating sort() in React

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-tosorted-immutable.md

Incorrect example that mutates the users prop array using .sort() inside useMemo, which can cause bugs with React state and props.

```typescript
function UserList({ users }: { users: User[] }) {
  // Mutates the users prop array!
  const sorted = useMemo(
    () => users.sort((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <div>{sorted.map(renderUser)}</div>
}
```

--------------------------------

### SVGO command to automate precision reduction

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rendering-svg-precision.md

Runs SVGO with --precision=1 and --multipass to automatically reduce coordinate precision in icon.svg, decreasing file size.

```bash
npx svgo --precision=1 --multipass icon.svg
```

--------------------------------

### Incorrect: Multiple filter calls (3 iterations)

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-combine-iterations.md

This example shows three separate filter calls on the same array, resulting in three iterations. It is marked as incorrect because it is inefficient.

```typescript
const admins = users.filter((u) => u.isAdmin)
const testers = users.filter((u) => u.isTester)
const inactive = users.filter((u) => !u.isActive)
```

--------------------------------

### Incorrect: Importing from barrel files (lucide-react and @mui/material)

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/bundle-barrel-imports.md

Shows the problematic pattern of importing from barrel files, which loads thousands of modules and adds significant runtime cost. The comments note the module counts and extra dev time.

```tsx
import { Check, X, Menu } from 'lucide-react'
// Loads 1,583 modules, takes ~2.8s extra in dev
// Runtime cost: 200-800ms on every cold start

import { Button, TextField } from '@mui/material'
// Loads 2,225 modules, takes ~4.2s extra in dev
```

--------------------------------

### Correct: Memoize or hoist RegExp

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-hoist-regexp.md

Correct approach: hoist a static regex to module scope or memoize the dynamic regex with useMemo to avoid recreation on every render.

```tsx
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

function Highlighter({ text, query }: Props) {
  const regex = useMemo(
    () => new RegExp(`(${escapeRegex(query)})`, 'gi'),
    [query]
  )
  const parts = text.split(regex)
  return <>{parts.map((part, i) => ...)}</>
}
```

--------------------------------

### Basic usage of createMarkupSerializer

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/_autodocs/api-reference/createMarkupSerializer.md

Basic usage of createMarkupSerializer with a simple ':__id__' template. Shows insert and findAll behavior, including the returned matches with index and display null.

```ts
import { createMarkupSerializer } from 'react-mentions-ts'

const serializer = createMarkupSerializer(':__id__')

serializer.insert({ id: 'wave', display: 'Wave' })
// → ':wave'

serializer.findAll('Hello :wave and :smile')
// →
// [
//   { markup: ':wave',  index: 6,  id: 'wave',  display: null },
//   { markup: ':smile', index: 15, id: 'smile', display: null },
// ]
```

--------------------------------

### Incorrect: forwardRef in React 19

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/react19-no-forwardref.md

Incorrect pattern in React 19. Using forwardRef is no longer necessary because ref is a regular prop for function components. This example is marked as incorrect.

```tsx
const ComposerInput = forwardRef<TextInput, Props>((props, ref) => {
  return <TextInput ref={ref} {...props} />
})
```

--------------------------------

### Correct: Immutable toSorted() in React

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-tosorted-immutable.md

Correct example using .toSorted() to create a new sorted array without mutating the original, preserving React's immutability model.

```typescript
function UserList({ users }: { users: User[] }) {
  // Creates new sorted array, original unchanged
  const sorted = useMemo(
    () => users.toSorted((a, b) => a.name.localeCompare(b.name)),
    [users]
  )
  return <div>{sorted.map(renderUser)}</div>
}
```

--------------------------------

### Imperative API - insertText

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/configuration.md

Demonstrates how to use the imperative API to programmatically insert text at the current caret position or replace the current selection using a ref to MentionsInput.

```APIDOC
## Imperative API - insertText

### Description
Attach a ref to MentionsInput to programmatically insert text at the current caret position or replace the current selection. The ref exposes an insertText method.

### Method
insertText

### Parameters
- **text** (string) - Required - The text to insert at the current caret position or replace the current selection.

### Example
```tsx
import { useRef, useState } from 'react'
import { Mention, MentionsInput, type MentionsInputHandle } from 'react-mentions-ts'

function ImperativeApiExample() {
  const mentionsRef = useRef<MentionsInputHandle>(null)
  const [value, setValue] = useState('')

  return (
    <>
      <button type="button" onClick={() => mentionsRef.current?.insertText('anything')}>
        Insert text
      </button>

      <MentionsInput
        ref={mentionsRef}
        value={value}
        onMentionsChange={({ value: nextValue }) => setValue(nextValue)}
      >
        <Mention trigger="@" data={users} />
      </MentionsInput>
    </>
  )
}
```
```

--------------------------------

### Incorrect: Repeated localStorage reads

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/js-cache-storage.md

Shows the anti-pattern of reading localStorage synchronously on every call, causing repeated expensive I/O. Use the Map cache example instead.

```typescript
function getTheme() {
  return localStorage.getItem('theme') ?? 'light'
}
// Called 10 times = 10 storage reads
```

--------------------------------

### Prefetch DNS and preconnect to third-party APIs

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rendering-resource-hints.md

Use prefetchDNS and preconnect to resolve DNS and establish connections to third-party domains before they are needed. This reduces latency for subsequent requests to those origins.

```tsx
import { preconnect, prefetchDNS } from 'react-dom'

export default function App() {
  prefetchDNS('https://analytics.example.com')
  preconnect('https://api.example.com')

  return <main>{/* content */}</main>
}
```

--------------------------------

### Correct: Module-level guard with didInit

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/advanced-init-once.md

Ensures initialization runs only once per app load, even if the component remounts.

```tsx
let didInit = false

function Comp() {
  useEffect(() => {
    if (didInit) return
    didInit = true
    loadFromStorage()
    checkAuthToken()
  }, [])

  // ...
}
```

--------------------------------

### Mention Props

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/README.md

Reference for all configurable props of the Mention component, including types, defaults, and descriptions.

```APIDOC
## Mention Props

### Description
Defines the configurable properties for the Mention component, allowing customization of trigger, data source, rendering, and behavior.

### Props

| Prop name        | Type                                                         | Default value              | Description                                                                                                                                                                                 |
| ---------------- | ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| trigger          | RegExp or string                                             | `'@'`                      | Defines the char sequence upon which to trigger querying the data source                                                                                                                    |
| data             | array or function `(query, { signal, cursor, reason })`      | `null`                     | An array of mentionable entries, or a filtering function that returns matching entries or a cursor page. Async providers receive an `AbortSignal` so stale requests can be cancelled safely |
| renderSuggestion | function (entry, search, highlightedDisplay, index, focused) | `null`                     | Allows customizing how mention suggestions are rendered (optional)                                                                                                                          |
| renderEmpty      | function `(query) => ReactNode`                              | `null`                     | Renders custom empty-state content when a query completes without any suggestions                                                                                                           |
| renderError      | function `(query, error) => ReactNode`                       | `null`                     | Renders custom error-state content when an async data provider rejects                                                                                                                      |
| markup           | string \| `MentionSerializer`                                | `'@[__display__](__id__)'` | Template string for stored markup, or pass a `MentionSerializer` instance for full control                                                                                                  |
| displayTransform | function (id, display)                                       | returns `display`          | Accepts a function for customizing the string that is displayed for a mention                                                                                                               |
| onAdd            | function ({id, display, startPos, endPos, serializerId})     | empty function             | Callback invoked when a suggestion has been added (optional)                                                                                                                                |
| appendSpaceOnAdd | boolean                                                      | `false`                    | Append a space when a suggestion has been added (optional)                                                                                                                                  |
| debounceMs       | number                                                       | `0`                        | Debounces async provider calls to reduce network chatter while typing                                                                                                                       |
| maxSuggestions   | number                                                       | unlimited                  | Caps the number of suggestions rendered from array results. Cursor page results own their page size and are not capped                                                                      |

### Notes
- For legacy markup customization, import `createMarkupSerializer` from `react-mentions` and pass `markup={createMarkupSerializer(':__id__')}`.
- When passing a `RegExp` as `trigger`, omit the global `/g` flag. The component clones the pattern internally; global regexes maintain shared `lastIndex` state and will skip matches across renders. Your custom `RegExp` should also be anchored to the end of the string with `$` to match only at the current cursor position, and it must contain two capturing groups: the first for the trigger and query (e.g., `@mention`), and the second for just the query (e.g., `mention`).
- To allow spaces (or other advanced patterns) after a trigger, pass a custom `RegExp`—for example `trigger={makeTriggerRegex('@', { allowSpaceInQuery: true })}`—instead of relying on a boolean flag. The `makeTriggerRegex` utility handles the regex construction for you.
```

--------------------------------

### Render saved value with MentionsText

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/advanced.md

Use MentionsText to display a stored markup value with mentions highlighted. The example shows a value like 'Hey @[Walter White](walter), are you there?' rendering as highlighted HTML.

```tsx
import { MentionsText } from 'react-mentions-ts'

// value: 'Hey @[Walter White](walter), are you there?'
;<MentionsText value={message.value} />
// renders: Hey <strong data-mention-id="walter">Walter White</strong>, are you there?
```

--------------------------------

### Preload fonts and preinit critical styles

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rendering-resource-hints.md

Preload a font file with the necessary options and preinit a critical stylesheet to fetch and apply it immediately. This is useful in a root layout to ensure critical resources are available early.

```tsx
import { preload, preinit } from 'react-dom'

export default function RootLayout({ children }) {
  // Preload font file
  preload('/fonts/inter.woff2', { as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' })

  // Fetch and apply critical stylesheet immediately
  preinit('/styles/critical.css', { as: 'style' })

  return (
    <html>
      <body>{children}</body>
    </html>
  )
}
```

--------------------------------

### Correct: Pass Props Instead

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rerender-no-inline-components.md

Correct pattern: define components at the top level and pass props to access parent variables, avoiding remounts.

```tsx
function Avatar({ src, theme }: { src: string; theme: string }) {
  return <img src={src} className={theme === 'dark' ? 'avatar-dark' : 'avatar-light'} />
}

function Stats({ followers, posts }: { followers: number; posts: number }) {
  return (
    <div>
      <span>{followers} followers</span>
      <span>{posts} posts</span>
    </div>
  )
}

function UserProfile({ user, theme }) {
  return (
    <div>
      <Avatar src={user.avatarUrl} theme={theme} />
      <Stats followers={user.followers} posts={user.posts} />
    </div>
  )
}
```

--------------------------------

### Incorrect: useWindowWidth with continuous width

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/best-practices/rerender-derived-state.md

Incorrect approach: subscribes to a continuous width value, causing re-renders on every pixel change. Use this only to contrast with the correct media-query approach.

```tsx
function Sidebar() {
  const width = useWindowWidth() // updates continuously
  const isMobile = width < 768
  return <nav className={isMobile ? 'mobile' : 'desktop'} />
}
```

--------------------------------

### Bridging pagination with Redux-Saga

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/docs/src/content/docs/configuration.md

Redux-Saga and similar async layers can bridge pagination by returning a promise from `data` and resolving it from the saga. The example shows a `data` function that dispatches a `fetchMentionPage` action with the query, cursor, signal, and resolve/reject callbacks.

```tsx
const data = (query: string, { cursor, signal }: MentionSearchContext) =>
  new Promise<UserPage>((resolve, reject) => {
    dispatch(fetchMentionPage({ query, cursor, signal, resolve, reject }))
  })
```

--------------------------------

### SSR and Next.js

Source: https://github.com/hbmartin/react-mentions-ts/blob/master/README.md

Notes on SSR compatibility and usage with Next.js App Router.

```APIDOC
## SSR and Next.js

### Description
The component is SSR-compatible out of the box. It guards against missing browser globals (`document`) during server rendering, so it works with Next.js, Remix, and other SSR frameworks without extra configuration.

### Usage in Next.js App Router
Add the `'use client'` directive to any file that renders `MentionsInput`:

```tsx
'use client'

import { MentionsInput, Mention } from 'react-mentions-ts'
```

No dynamic imports or `next/dynamic` wrappers are needed.
```
Tokens:
Raw