MentionModule

Auto-imported: NO (requires manual addition to the modules option)

This module allows you to trigger suggestions when typing a specific character (like @ or #). It supports both static data and remote data fetching via AJAX.

Options

Option	Type	Description	Default
trigger	string	The character that triggers the suggestion list.	'@'
data	array	A static list of items. Each item must be an object: {'id': 1, 'value': 'Name'}.	[]
remote_url	string	URL for AJAX search. Use {query} as a placeholder for the user input.	null
min_chars	int	Minimum characters to type after the trigger before showing suggestions.	1
max_results	int	Maximum number of results displayed in the suggestion list.	10

Behavior

• Triggering: The list appears when the trigger character is followed by at least min_chars characters (without spaces).
• Navigation:
  • ArrowUp / ArrowDown: Move selection in the list.
  • Enter / Tab: Select the current item.
  • Escape: Close the suggestion list.
• Insertion: When selected, the trigger and the typed query are replaced by a Mention Blot (a styled <span>).

Remote Search (AJAX)

When using remote_url, your API must return a JSON array of objects with at least id and value properties:

[
  { "id": "user-1", "value": "John Doe" },
  { "id": "user-2", "value": "Jane Smith" }
]

Example URL configuration: https://api.example.com/users?search={query}

Usage Examples

1. Basic usage with static data:

'modules' => [
    new MentionModule(options: [
        'trigger' => '@',
        'data' => [
            ['id' => 1, 'value' => 'Matthieu'],
            ['id' => 2, 'value' => 'Gemini'],
            ['id' => 3, 'value' => 'Symfony'],
        ],
    ]),
],

2. Advanced usage with remote search (e.g., Tags):

'modules' => [
    new MentionModule(options: [
        'trigger' => '#',
        'remote_url' => '/api/tags/search?q={query}',
        'min_chars' => 2,
        'max_results' => 5,
    ]),
],

3. Multiple triggers:

If you need multiple triggers (e.g., @ for users AND # for tags), you can pass multiple instances. Make sure each one has a unique name starting with mention-:

'modules' => [
    new MentionModule(name: 'mention-users', options: [
        'trigger' => '@',
        'remote_url' => '/api/users/search?q={query}',
    ]),
    new MentionModule(name: 'mention-tags', options: [
        'trigger' => '#',
        'data' => [
            ['id' => 'tech', 'value' => 'technology'],
            ['id' => 'news', 'value' => 'news'],
        ],
    ]),
],

Customizing the look

The mentions and the suggestion list can be styled using CSS. Here are the default classes:

• .ql-mention: The inserted mention in the editor.
• .ql-mention-list: The floating suggestion container.
• .ql-mention-item: An item in the list.
• .ql-mention-item.selected: The currently highlighted item.

Example to customize the mention color:

.ql-editor .ql-mention {
    background-color: #fce4ec;
    color: #c2185b;
}