Describe new API related to triggers by serhiipylypchuk1991 · Pull Request #46 · DHTMLX/docs-richtext

serhiipylypchuk1991 · 2026-05-27T06:22:22Z

No description provided.

- new API reference page for the hide-suggest event - documents when the dropdown closes (selection, Escape, cursor leaves trigger, empty result)

- new API reference page for the insert-token event - documents callback fields (id, label, url, trigger, showTrigger)

- new API reference page for the show-suggest event - documents callback fields (trigger, query, items, pos) and intercept example

- new API reference page for the triggers property - covers static array, sync function, async function data sources - documents suggestion item fields and rendered token CSS targeting

- new API reference page for the triggerTemplate property - documents callback parameters (data, trigger) and template usage - includes tip on overriding the dropdown anchor width

- new guide covering trigger characters, data source forms, token rendering, and event handling - examples for static array, sync function, async function, and custom dropdown templates

- list hide-suggest, insert-token, and show-suggest in the events table

- list triggers and triggerTemplate in the properties table

- list triggers in the property overview with a link to the Mentions and tags guide

- update anchor in whats_new from #custom-toolbar-controls to #add-custom-toolbar-controls to match the heading in configuration.md

- add hide-suggest, insert-token, show-suggest under events - add triggers and trigger-template under properties - add mentions_and_tags under guides

kullias

the code changes somewhat in a side branch on custom actions, I added comments, for source code DM either me or the author of the code, we'll point to the branch

kullias · 2026-06-02T18:19:47Z

+    url: string,
+    trigger: string,
+    showTrigger?: boolean
+}) => boolean | void;


data: ISuggestionItem; trigger: string; showTrigger?: boolean; action?: (config: ISuggestionItem) => void; //where export interface ISuggestionItem { id?: TID; label?: string; url?: string; [key: string]: any; }

action added a couple of days ago, the rest not sure when changed, but changed

Done. Updated the Usage block: id/label/url are now wrapped in a data object (all optional, plus a note for custom fields), and action? was added.

kullias · 2026-06-02T18:24:07Z

+- `url` - the url associated with the item (becomes the `href` attribute of the inserted token)
+- `trigger` - the trigger character that opened the dropdown (for example, `"@"` or `"#"`)
+- `showTrigger` - when `false`, RichText inserts only `label`; otherwise it also shows the trigger character (default)
+


descriptions are fine, just update the structure (data carries some of them)
and add action - custom action that executes when the option is chosen
also worth noting that showTrigger can't be used together with action - it's either or. action is prioritized. is action is set, showTrigger is assumed false. the command is executed, the /sometext is removed.

Done. data now carries the item fields, and added action with a note that it takes priority over showTrigger: when action is set, the typed text (trigger + query) is removed and showTrigger has no effect.

kullias · 2026-06-02T18:25:09Z

+editor.api.on("insert-token", (obj) => {
+    console.log(obj);
+    console.log(`Inserted ${obj.trigger}${obj.label} (id: ${obj.id})`);
+});


editor.api.on("insert-token", ({ data, trigger, showTrigger }) => { console.log(`Inserted ${trigger}${data.label} (id: ${data.id})`); });

Done. Example handler now uses ({ data, trigger, showTrigger }) and logs data.label / data.id.

kullias · 2026-06-02T18:25:43Z

+editor.api.on("insert-token", ({ trigger, label, id }) => {
+    console.log(`Inserted ${trigger}${label} (id: ${id})`);
+});
+~~~


editor.api.on("insert-token", ({ data, trigger, showTrigger }) => { console.log(`Inserted ${trigger}${data.label} (id: ${data.id})`); });

Done. Aligned the guide handler to the same ({ data, trigger, showTrigger }) form.

kullias · 2026-06-02T18:30:07Z

+        | ((query: string) =>
+            Array<{ id?: string; label?: string; url?: string }>
+            | Promise<Array<{ id?: string; label?: string; url?: string }>>),
+    showTrigger?: boolean


also add action?: (item) => void - that's the same custom action that in "insert-token"

Done. Added action?: (item) => void to the triggers Usage block and a matching field description, plus a Custom action section.

kullias · 2026-06-02T18:47:15Z

+"show-suggest": ({
+    trigger: string,
+    query: string,
+    items: Array<{ id: string, label: string, url: string }>,


this one now allows also arbitrary keys. in TS that would be [key: string]: any - custom fields used by triggerTemplate examples like image, name. and the ones you already have here are all optional.

Done. items is now typed with optional id/label/url plus arbitrary custom keys, and the description mentions custom fields like image/name used by triggerTemplate.

- add `action` field to triggers config with Custom action section (emoji insertion and slash-style command menu examples) - update insert-token event payload: id/label/url replaced by `data` object carrying the picked item plus custom fields; add `action` - note that `action` takes priority over `showTrigger` - show-suggest items now documented as optional fields + custom keys - extend mentions guide with custom action examples - fix typos, a broken anchor, and align wording across pages

- destructure ({ data, trigger, showTrigger }) to match the insert-token event docs and the PR review suggestion

DmitriySlabodchikov · 2026-06-03T16:10:12Z

+
+- `id` - (optional) unique identifier saved on the inserted token. If omitted, RichText generates an ID automatically
+- `label` - (required) the text shown in the dropdown and inserted into the document
+- `url` - (optional) URL associated with the item. RichText stores the inserted token URL as the `href` attribute.


ctrl-click to open this link

DmitriySlabodchikov · 2026-06-03T16:15:04Z

+When a user selects an item in the dropdown, RichText inserts a non-editable token element into the document:
+
+~~~html {}
+<a data-token="@" data-token-id="alice" href="mailto:alice@example.com">@Alice</a>


Where:

@ is trigger

alice is id

mailto:alice@example.com is url

@Alice - combination of trigger and label, in case of showTrigger: false it would be just Alice

DmitriySlabodchikov · 2026-06-03T16:22:00Z

+
+#### Add emoji
+
+A common use case is inserting an emoji from a `:` trigger, where each item contains a custom `code` field. Pair `action` with [`triggerTemplate`](api/config/trigger-template.md) so the dropdown shows the emoji itself instead of just its label:


maybe it's better to use this snippet code with categories (it is also a good example of custom data filtering): https://snippet.dhtmlx.com/r16rmt4m

DmitriySlabodchikov · 2026-06-03T16:25:08Z

+new richtext.Richtext("#root", {
+    triggers: [{ trigger: "@", data: people }],
+    triggerTemplate: template(obj => {
+        if (obj.trigger === "@") {


maybe add one more trigger, because otherwise there is no point in checking for equality to a "@"

DmitriySlabodchikov · 2026-06-03T16:27:15Z

+- `trigger` - the trigger character that opened the dropdown (`"@"`, `"#"`, etc.)
+
+:::tip
+The dropdown anchor has a fixed default width of `160px`. To make room for a wider template, override the width from a parent stylesheet (`!important` is needed because the widget sets the default via its own scoped CSS):


u can just make bit more complex css rule, like .wx-editor .wx-suggest-anchor instead of !important

DmitriySlabodchikov · 2026-06-03T16:32:49Z

+Each item in the `data` object (or each item returned by a function) has the following fields:
+
+- `id` - (optional) unique identifier saved on the inserted token. If omitted, RichText generates an ID automatically
+- `label` - (required) the text shown in the dropdown and inserted into the document


not really required, u can use custom template (for example: triggerTemplate: template(({data}) => data.id))

serhiipylypchuk1991 added 11 commits May 27, 2026 09:16

[add] hide-suggest event docs

3d4da9d

- new API reference page for the hide-suggest event - documents when the dropdown closes (selection, Escape, cursor leaves trigger, empty result)

[add] insert-token event docs

6eac577

- new API reference page for the insert-token event - documents callback fields (id, label, url, trigger, showTrigger)

[add] show-suggest event docs

34f4c79

- new API reference page for the show-suggest event - documents callback fields (trigger, query, items, pos) and intercept example

[add] triggers config docs

44b66d8

- new API reference page for the triggers property - covers static array, sync function, async function data sources - documents suggestion item fields and rendered token CSS targeting

[add] triggerTemplate config docs

a49929b

- new API reference page for the triggerTemplate property - documents callback parameters (data, trigger) and template usage - includes tip on overriding the dropdown anchor width

[add] Mentions and tags guide

d1adb47

- new guide covering trigger characters, data source forms, token rendering, and event handling - examples for static array, sync function, async function, and custom dropdown templates

[update] add suggestion events to events overview

6948c9c

- list hide-suggest, insert-token, and show-suggest in the events table

[update] add trigger configs to properties overview

ce748b7

- list triggers and triggerTemplate in the properties table

[update] mention triggers in configuration guide

90c074d

- list triggers in the property overview with a link to the Mentions and tags guide

[fix] correct anchor for custom toolbar controls link

d764692

- update anchor in whats_new from #custom-toolbar-controls to #add-custom-toolbar-controls to match the heading in configuration.md

[update] register trigger pages in sidebar

f888bf7

- add hide-suggest, insert-token, show-suggest under events - add triggers and trigger-template under properties - add mentions_and_tags under guides

serhiipylypchuk1991 self-assigned this May 27, 2026

serhiipylypchuk1991 requested a review from kullias May 27, 2026 11:48

kullias requested changes Jun 2, 2026

View reviewed changes

serhiipylypchuk1991 added 2 commits June 3, 2026 18:27

[update] align insert-token handler in guide

2f2a6b7

- destructure ({ data, trigger, showTrigger }) to match the insert-token event docs and the PR review suggestion

DmitriySlabodchikov reviewed Jun 3, 2026

View reviewed changes


		#### Add emoji

		A common use case is inserting an emoji from a `:` trigger, where each item contains a custom `code` field. Pair `action` with [`triggerTemplate`](api/config/trigger-template.md) so the dropdown shows the emoji itself instead of just its label:

Conversation

serhiipylypchuk1991 commented May 27, 2026

Uh oh!

kullias left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DmitriySlabodchikov Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

DmitriySlabodchikov Jun 3, 2026 •

edited

Loading