# Mentionly

A mention engine for AI inputs, keeping selected objects intact as text is edited and saved

Source: https://works.im0o.top/en/projects/mentionly/
Date: 2026-02-11
Tags: Developer tools, Editor, Structured references, TypeScript, Library development

## Project links

- [Source](https://github.com/jz0ojiang/mentionly)
- [Playground](https://im0o.top/mentionly/)


AI chat inputs often need to reference a file, project, or person. Rendering `@name` is easy; keeping the object identifiable after its name changes, preventing Backspace from leaving half a label behind, and deciding what to send to the backend take more work.

Mentionly is the input library I wrote for those cases. Text and mentions share an editor; selected objects are edited as whole entities, and submission produces structured content rather than only a concatenated string.

## A visible label and an object identity

In “Please check @Alice,” the screen displays a name while the application may need a user ID. A mention keeps both: `label` for display, with `id` and `data` for the application.

```ts
[
  { type: 'text', text: 'Please check ' },
  {
    type: 'mention',
    trigger: '@',
    id: 'u1',
    label: 'Alice',
    data: { kind: 'user', userId: 'u1' }
  }
]
```

This is an example submission value. Ordinary text remains freely editable. A selected mention is atomic: editing half its name must not silently retain the original object's identity. Copying, pasting, deleting, and restoring content all work with the segmented value.

Several triggers can be configured. An application might use `@` for people or files, and `#` or `/` for other objects and commands. Its `toData()` function captures the business payload when an item is selected.

![The displayed label and submitted ID belong to the same mention object](https://image.im0o.top/2026/20261117104320683.webp)

## IME and asynchronous suggestions

Real suggestion lists usually come from search APIs. A user can replace a query before its earlier request returns, so debouncing alone is insufficient: stale results need to be discarded, and paginated sources need a way to load more.

Chinese input composition needs its own handling. Unconfirmed phonetic input should not become a completed query, and Enter used to choose a character should not submit the message.

The suggestion position follows the caret and supports rendering outside the editor's ancestors so `overflow` does not clip it. Keyboard selection, focus, and accessibility relationships are handled alongside this behavior; applications remain free to design the list.

![Suggestions follow the current input; a late response to an older query cannot replace them](https://image.im0o.top/2026/20261117104315798.webp "Suggestions follow the current input; a late response to an older query cannot replace them")

## From a Vue component to several adapters

Version 1.x centered on Vue 3's `useMention` and ready-made components. As other interfaces needed the same behavior, I extracted trigger detection, DOM editing, serialization, keyboard controls, and IME handling into the framework-independent `@mentionly/core`.

Version 2.0 adds Vue, React, and Svelte adapters. Vue retains `MentionInput` and `MentionList`; React and Svelte expose headless interfaces for application-owned rendering. The original `mentionly` package forwards the Vue implementation so existing integrations can migrate gradually.

I also added AI SDK and MCP converters and version-matched `llms.txt` files in the packages. A coding agent integrating the editor can read the rules for the installed version, including why the framework should not render children inside the DOM managed by the editor.

This portfolio uses the React adapter in its input.

[Live demo](https://im0o.top/mentionly?lang=en) · [Source](https://github.com/jz0ojiang/mentionly)

