Use markup mentions.

Use the markup parser when your editor already stores the selected model ID. The ID remains stable when a visible handle changes.

1. Select the markup parser

Override mentionParser() on the source model:

use Byrcsc\Mentions\Concerns\HasMentions;
use Illuminate\Database\Eloquent\Model;

class Comment extends Model
{
    use HasMentions;

    /** @var list<string> */
    protected array $mentionableAttributes = ['body'];

    protected function mentionParser(): string
    {
        return 'markup';
    }
}

The shipped configuration maps markup to MarkupMentionParser.

2. Store the target attributes

Write data-mention-id on the element representing a mention:

<p>
  Thanks
  <span data-mention-id="42" data-mention-type="users">@jane</span>
</p>

The type selects the users resolver definition. The resolver passes the ID to the configured User model's whereKey() query.

Attribute order and quote style do not matter. The parser ignores an empty ID.

3. Use types for several target models

Match markup types to resolver keys:

'resolvers' => [
    'users' => [
        'model' => App\Models\User::class,
        'column' => 'username',
    ],
    'teams' => [
        'model' => App\Models\Team::class,
        'column' => 'slug',
    ],
],

<span data-mention-id="42" data-mention-type="users">@jane</span>
<span data-mention-id="01JTEAM" data-mention-type="teams"> @engineering </span>

When data-mention-type is absent, the first resolver definition containing a model supplies the target class. Include the type when more than one class can be mentioned.

Preserve the target ID

The parser keeps IDs as strings. Integer keys, UUIDs, and ULIDs use the same path.

An element whose target no longer exists becomes unresolved during the next sync. Synchronization removes existing mention rows for that source if no other candidate finds the target.

Treat stored HTML as untrusted

MarkupMentionParser finds attributes with DOMDocument. It does not sanitize the HTML or verify that the displayed handle belongs to the target ID.

Sanitize and escape content according to your application's rendering rules. Authorize the selected target before storing editor output.

What to read next

• Parsing text for markup deduplication and malformed HTML behavior.
• Resolving targets for typed and untyped ID lookup.
• Mention groups to query non-user targets.