# Mention Menu

## Example

```svelte
<script lang="ts">
	import {
		CoreRichTextEditor,
		MentionNode,
		MentionMenu,
		type MentionItem,
		type SvelteTiptap
	} from '@foxui/all';
	import { Avatar, cn, Box } from '@foxui/all';
	import type { Readable } from 'svelte/store';

	let editor = $state<Readable<SvelteTiptap.Editor>>();

	async function searchBlueskyUsers(query: string): Promise<MentionItem[]> {
		const res = await fetch(
			`https://public.api.bsky.app/xrpc/app.bsky.actor.searchActorsTypeahead?q=${query}&limit=5`
		);
		if (!res.ok) return [];
		const data = await res.json();
		return data.actors.map(
			(actor: { did: string; handle: string; avatar?: string; displayName?: string }) => ({
				id: actor.did,
				label: actor.handle,
				avatar: actor.avatar,
				data: { displayName: actor.displayName }
			})
		);
	}
</script>

<Box class="not-prose">
	<CoreRichTextEditor
		bind:editor
		placeholder="Type @ to mention someone..."
		extraExtensions={[
			MentionNode.configure({
				HTMLAttributes: { class: 'text-accent-600 dark:text-accent-400 font-medium' }
			})
		]}
		class="min-h-24"
	>
		{#if $editor}
			<MentionMenu editor={$editor} items={searchBlueskyUsers}>
				{#snippet item({ item: mentionItem, isActive, select })}
					<button
						onclick={select}
						class={cn(
							'text-base-900 dark:text-base-200 flex w-full cursor-pointer items-center gap-3 px-3 py-2 text-sm',
							isActive
								? 'text-accent-700 dark:text-accent-400 bg-accent-500/10'
								: 'hover:bg-accent-500/10'
						)}
					>
						<Avatar src={mentionItem.avatar} alt="" class="size-6 rounded-full" />
						<span class="flex flex-col items-start">
							<span class="font-medium">{mentionItem.label}</span>
							{#if mentionItem.data?.displayName}
								<span class="text-base-500 text-xs">{mentionItem.data.displayName}</span>
							{/if}
						</span>
					</button>
				{/snippet}
			</MentionMenu>
		{/if}
	</CoreRichTextEditor>
</Box>
```

## Documentation

## Usage

Add `MentionNode` via `extraExtensions`, then render `MentionMenu` as a child — similar to how `BubbleMenu` and `FloatingMenu` work in svelte-tiptap.

```svelte
<script lang="ts">
	import {
		CoreRichTextEditor,
		MentionNode,
		MentionMenu,
		type MentionItem
	type SvelteTiptap
	} from '@foxui/text';
	import type { Readable } from 'svelte/store';

	let editor = $state<Readable<SvelteTiptap.Editor>>();

	async function searchUsers(query: string): Promise<MentionItem[]> {
		const res = await fetch(`/api/users?q=${query}`);
		const users = await res.json();
		return users.map((u) => ({
			id: u.id,
			label: u.name,
			avatar: u.avatarUrl
		}));
	}
</script>

<CoreRichTextEditor
	bind:editor
	extraExtensions={[MentionNode]}
>
	{#if $editor}
		<MentionMenu editor={$editor} items={searchUsers}>
			{#snippet item({ item: mentionItem, isActive, select })}
				<button onclick={select}>
					{mentionItem.label}
				</button>
			{/snippet}
		</MentionMenu>
	{/if}
</CoreRichTextEditor>
```

## Custom rendering

The `item` snippet receives `{ item, isActive, select }`. Use this to fully customize how each suggestion looks — add avatars, secondary text, keyboard highlight styling, etc.

If no `item` snippet is provided, a minimal default rendering is used.

## How it works

`MentionNode` is a tiptap Node extension that defines an inline, non-editable mention node with `id`, `label`, and optional `data` attributes.

`MentionMenu` follows the same pattern as svelte-tiptap's `BubbleMenu` — it takes an `editor` prop and registers a suggestion plugin on mount. The popup is positioned using `@floating-ui/dom` and supports keyboard navigation (Arrow keys + Enter + Escape).

## Works with any editor

Both `CoreRichTextEditor` and `RichTextEditor` support `extraExtensions` to add extensions without replacing defaults. You can also use `MentionNode` + `MentionMenu` with any tiptap editor setup.

## API Reference

### MentionMenu
A suggestion popup component for @mentions. Registers a tiptap suggestion plugin on mount, like BubbleMenu/FloatingMenu.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| editor | `Editor` | `-` | The tiptap editor instance. (required) |
| items | `(query: string) => MentionItem[] | Promise<MentionItem[]>` | `-` | Function that returns mention suggestions for a search query. (required) |
| char | `string` | `'@'` | Trigger character for the mention popup. |
| minQueryLength | `number` | `2` | Minimum characters after trigger before searching. |
| pluginKey | `string` | `'mentionMenu'` | Unique key for the suggestion plugin. |
| item | `Snippet<[{ item: MentionItem; isActive: boolean; select: () => void }]>` | `-` | Snippet for custom rendering of each suggestion item. |
| class | `string` | `-` | CSS classes for the popup container. |

### MentionNode
A tiptap Node extension for inline mention nodes. Add to editor extensions to enable mentions.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| HTMLAttributes | `Record<string, unknown>` | `{}` | HTML attributes applied to mention nodes. |
| renderLabel | `({ node }) => string` | `'({ node }) => `@${node.attrs.label}`'` | Custom function to render the mention label text. |

### MentionItem
The data shape for mention suggestions.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| id | `string` | `-` | Unique identifier for the mention (e.g., user ID, DID). (required) |
| label | `string` | `-` | Display label for the mention (e.g., username, handle). (required) |
| avatar | `string` | `-` | Optional avatar URL. |
| data | `Record<string, unknown>` | `-` | Optional extra data stored on the mention node. |