prompt-mentions

A beautiful React component library for building AI prompts with @mentions. Features a sleek mention menu, nested submenus, keyboard navigation, custom theming, and file extension icons.


Features

- 🎨 Multiple preset themes — Light, Cursor Dark, GitHub Dark, Minimal
- 🎯 Multiple trigger characters — Use @, #, /, or any character
- 📁 Nested menus — Navigate hierarchical options with Tab/Escape
- ⌨️ Full keyboard navigation — Arrow keys, Enter, Tab, Escape
- 🏷️ Mention pills — Beautiful styled tags for selected mentions
- 🖼️ Icons custom and auto — Add icons to menu items, mentions. File extension icons are supported.
- 🎛️ Imperative API — Programmatically append mentions via ref
- 📱 Message component — Render sent messages with formatted mentions
- 🎨 Fully CSS customizable — CSS variables and theme objects

Installation

``bash
npm install prompt-mentions
`

`bash
yarn add prompt-mentions
`

`bash
pnpm add prompt-mentions
`

Quick Start

`tsx
import { Prompt } from "prompt-mentions";
import "prompt-mentions/style.css";

const options = [
{ id: "alice", label: "Alice Johnson" },
{ id: "bob", label: "Bob Smith" },
{ id: "main-ts", label: "main.ts" },
];

function App() {
return (
placeholder="Type @ to mention..."
mentionConfigs={[{ trigger: "@", options }]}
onChange={(value, mentions) => {
console.log("Value:", value);
console.log("Mentions:", mentions);
}}
/>
);
}
`

Components

$3

The main input component with mention support.

`tsx
import { Prompt } from "prompt-mentions";
`

#### Props

| Prop | Type | Default | Description |
| ------------------ | ------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------- |
| initialValue | string | "" | Initial text content with optional mentions in @[id] format |
| placeholder | string | "" | Placeholder text when input is empty |
| mentionConfigs | MentionConfig[] | [{ trigger: '@', options: [] }] | Array of mention trigger configurations |
| theme | PresetThemeName \| PromptTheme | — | Theme preset name or custom theme object |
| className | string | "" | Additional CSS class name |
| style | CSSProperties | — | Inline styles |
| extensionIcons | boolean | false | Auto-add file icons based on extension |
| onChange | (value: string, mentions: SelectedMention[]) => void | — | Called on every text change |
| onEnter | (value: string, mentions: SelectedMention[]) => void | — | Called when Enter is pressed |
| onMentionAdded | (mention: SelectedMention) => void | — | Called when a mention is selected |
| onMentionDeleted | (mention: SelectedMention) => void | — | Called when a mention is removed |
| onMentionClick | (mention: SelectedMention) => void | — | Called when a mention pill is clicked |

#### MentionConfig

`typescript
interface MentionConfig {
trigger: string; // Character that triggers the menu (e.g., '@', '#', '/')
options: MentionOption[]; // Array of mention options
menuPosition?: "above" | "below"; // Menu position relative to cursor
showTrigger?: boolean; // Show trigger character in pill (default: false)
}
`

#### MentionOption

`typescript
interface MentionOption {
id: string; // Unique identifier
label: string; // Display text
icon?: ReactNode; // Optional icon component
type?: "item" | "divider" | "title"; // Item type
children?: MentionOption[]; // Nested submenu items
labelRight?: string; // Secondary label (e.g., file path)
indent?: number; // Visual indent level
}
`

$3

Display sent messages with formatted mention pills.

`tsx
import { Message } from "prompt-mentions";

value="Hello @[alice]! Please review @[main-ts]"
mentionConfigs={[{ trigger: "@", options }]}
onMentionClick={(mention) => console.log("Clicked:", mention)}
/>;
`

#### Props

| Prop | Type | Default | Description |
| ---------------- | -------------------------------- | -------------------- | -------------------------------------------------- |
| value | string | — | Message text with mentions in trigger[id] format |
| mentionConfigs | MessageMentionConfig[] | [{ trigger: '@' }] | Mention configurations for label/icon lookup |
| theme | PresetThemeName \| PromptTheme | — | Theme preset or custom theme |
| className | string | "" | Additional CSS class name |
| style | CSSProperties | — | Inline styles |
| extensionIcons | boolean | false | Auto-add file icons based on extension |
| onMentionClick | (mention) => void | — | Called when a mention pill is clicked |

Theming

$3

`tsx
// Default light theme
// Cursor IDE dark theme
// GitHub dark theme
// Clean minimal theme
`

$3

Pass a PromptTheme object for full control:

`tsx
const customTheme: PromptTheme = {
backgroundColor: "#1a1625",
color: "#e0d4f7",
placeholderColor: "#6b5b8c",
fontSize: "14px",
borderRadius: "12px",
borderColor: "#2d2640",
focusBorderColor: "#9c6ade",

menu: {
backgroundColor: "#1a1625",
borderColor: "#2d2640",
color: "#c4b5dc",
itemHoverColor: "#2d2640",
},

pill: {
backgroundColor: "linear-gradient(135deg, #7c3aed, #c026d3)",
borderRadius: "8px",
color: "white",
},
};

;
`

$3

Override only specific properties:

`tsx
theme={{
focusBorderColor: "#f43f5e",
pill: {
backgroundColor: "#16a34a",
},
}}
/>
`

$3

All styling is controlled via CSS variables. Override them in your CSS:

`css
.prompt-container {
--prompt-background-color: white;
--prompt-color: black;
--prompt-placeholder-color: #9ca3af;
--prompt-border-radius: 0.375rem;
--prompt-border-color: #d1d5db;
--prompt-focus-border-color: #6366f1;

--prompt-mention-pill-background-color: linear-gradient(
135deg,
#6366f1,
#8b5cf6
);
--prompt-mention-pill-color: white;
--prompt-mention-pill-border-radius: 9999px;

--prompt-mention-menu-background-color: white;
--prompt-mention-menu-border-color: #e5e7eb;
--prompt-mention-menu-item-hover-color: #f3f4f6;
}
`

Advanced Usage

$3

Configure different triggers for different types of mentions:

`tsx
placeholder="Type @, #, or / ..."
mentionConfigs={[
{ trigger: "@", options: peopleOptions },
{ trigger: "#", options: tagOptions },
{ trigger: "/", options: commandOptions, menuPosition: "above" },
]}
/>
`

$3

Create hierarchical option structures:

`tsx
const options = [
{
id: "team",
label: "Team Members",
icon: ,
children: [
{ id: "alice", label: "Alice Johnson" },
{ id: "bob", label: "Bob Smith" },
],
},
{
id: "projects",
label: "Projects",
icon: ,
children: [
{ id: "alpha", label: "Project Alpha" },
{ id: "beta", label: "Project Beta" },
],
},
];
`

Navigate with:

- Tab or → — Enter submenu
- Escape or ← — Exit submenu

$3

Add icons and secondary labels to options:

`tsx
const fileOptions = [
{
id: "prompt-tsx",
label: "Prompt.tsx",
labelRight: "src/components/",
icon: ,
indent: 1,
},
];
`

$3

Automatically add file type icons based on file extensions:

`tsx
extensionIcons={true}
mentionConfigs={[{ trigger: "@", options: fileOptions }]}
/>
`

Supports: .ts, .tsx, .js, .jsx, .css, .html, .json, .md, .py, .go, .rs, .sql, and many more.

$3

Organize options with visual separators:

`tsx
const options = [
{ id: "title-people", label: "People", type: "title" },
{ id: "alice", label: "Alice" },
{ id: "bob", label: "Bob" },
{ id: "divider-1", label: "", type: "divider" },
{ id: "title-files", label: "Files", type: "title" },
{ id: "readme", label: "README.md" },
];
`

$3

Use the imperative handle to control the prompt externally:

`tsx
import { useRef } from "react";
import { Prompt, PromptHandle, MentionOption } from "prompt-mentions";

function MyComponent() {
const promptRef = useRef(null);

const handleAddMention = (option: MentionOption) => {
// Append mention with default trigger (@)
promptRef.current?.appendMention(option);

// Or with a specific trigger
promptRef.current?.appendMention(option, "#");

// Focus the input
promptRef.current?.focus();
};

const handleInsertText = () => {
// Insert text at current cursor position (or at end if not focused)
// Behaves like typing - triggers mention menu when a trigger character is inserted
promptRef.current?.insertText("Hello ");

// Insert a trigger to open the mention menu
promptRef.current?.insertText("@");
};

return (
<>
ref={promptRef}
mentionConfigs={[
{ trigger: "@", options: userOptions },
{ trigger: "#", options: tagOptions },
]}
/>
handleAddMention({ id: "alice", label: "Alice" })}>
Add @Alice

Insert Text

);
}
`

#### PromptHandle Methods

| Method | Signature | Description |
| --------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| appendMention | (option: MentionOption, trigger?: string) => void | Appends a mention pill to the end of the input |
| focus | () => void | Focuses the prompt input |
| insertText | (text: string) => void | Inserts text at cursor position. Behaves like typing—triggers mention menu when a trigger character is inserted |

$3

Pre-populate the input with existing mentions:

`tsx
initialValue="Hello @[alice]! Please check @[main-ts]"
mentionConfigs={[{ trigger: "@", options }]}
/>
`

The format is trigger[id] where id matches an option's id field.

Exports

`typescript
// Components
export { Prompt, Message } from "prompt-mentions";

// Types
export type {
MentionOption,
MentionItemType,
SelectedMention,
PromptTheme,
PresetThemeName,
} from "prompt-mentions";

// Theme utilities
export { themeToStyles, presetThemes, defaultTheme } from "prompt-mentions";

// Extension icon utilities
export {
getExtensionIcon,
extensionIconMap,
filenameIconMap,
DefaultFileIcon,
DefaultFolderIcon,
} from "prompt-mentions";
`

Keyboard Shortcuts

| Key | Action |
| -------------- | ---------------------------------------- |
| ↑ / ↓ | Navigate menu options |
| Enter | Select highlighted option |
| Tab / → | Enter submenu (if available) |
| Escape / ← | Exit submenu or close menu |
| Backspace | Delete mention (when cursor is adjacent) |

Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

Development

`bash


Install dependencies

npm install

Run Storybook for development

npm run storybook

Run tests

npm run test

Build the library

npm run build
`

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to the main repository.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)
5. Open a Pull Request

License

MIT © (https://github.com/getnao/prompt-mentions/blob/main/LICENSE)

---

Made with ❤️ by nao Labs