@skyastrall/mentions-react

Multi-trigger inline suggestions for React. Drop-in component, compound components, or headless hook.

Docs · Playground · GitHub

Install

npm install @skyastrall/mentions-react

Requires react and react-dom >= 18 (React 18 and 19 are both supported).

Quick Start

import { Mentions } from "@skyastrall/mentions-react";

const users = [{ id: "1", label: "Alice" }, { id: "2", label: "Bob" }];
const tags = [{ id: "t1", label: "design" }, { id: "t2", label: "bug" }];
const commands = [{ id: "c1", label: "summarize" }];

<Mentions
  triggers={[
    { char: "@", data: users, color: "rgba(99,102,241,0.25)" },
    { char: "#", data: tags, color: "rgba(16,185,129,0.25)" },
    { char: "/", data: commands, color: "rgba(245,158,11,0.25)" },
  ]}
  onChange={(markup, plainText) => console.log(markup)}
/>

Features

• Multi-trigger (@mentions, #tags, /commands)
• Per-trigger highlight colors
• Ghost text / AI completions
• Async data with loading states
• Single-line mode
• Full ARIA keyboard navigation
• Controlled and uncontrolled modes
• ~4 KB minified + gzipped (~6 KB core)

API Layers

1. <Mentions> — drop-in, works out of the box
2. Compound components — Mentions.Editor, Mentions.Portal, Mentions.List, Mentions.Item, Mentions.Empty, Mentions.Loading
3. useMentions() — headless hook, full control

See the full documentation for API reference and guides.

Next.js App Router / React Server Components

The bundle ships with a 'use client' directive at the top, so importing <Mentions> or useMentions() from a Client Component works out of the box.

If you need the pure data helpers (extractMentions, parseMarkup, markupToPlainText, buildMentionHTML) inside a Server Component (for SSR, RSC, or edge runtimes), import them directly from @skyastrall/mentions-core — the framework-agnostic engine has no 'use client' boundary:

import { extractMentions } from "@skyastrall/mentions-core";

const triggers = [{ char: "@", data: [] }];

export default async function Page({ comment }: { comment: string }) {
  const mentions = extractMentions(comment, triggers); // server-safe
  return <ul>{mentions.map((m) => <li key={m.id}>@{m.label}</li>)}</ul>;
}

License

MIT — Built by SkyAstrall