|
| 1 | +--- |
| 2 | +sidebar_label: triggers |
| 3 | +title: triggers Config |
| 4 | +description: You can learn about the triggers config in the documentation of the DHTMLX JavaScript RichText library. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX RichText. |
| 5 | +--- |
| 6 | + |
| 7 | +# triggers |
| 8 | + |
| 9 | +### Description |
| 10 | + |
| 11 | +@short: Optional. Defines dropdown triggers for inserting mentions, tags, and other tokens |
| 12 | + |
| 13 | +When a user types a configured character (for example, `@` or `#`), RichText opens a dropdown with predefined items. When the user selects an item, RichText inserts it into the document as a non-editable token (`<a data-token="..." data-token-id="...">`). |
| 14 | + |
| 15 | +### Usage |
| 16 | + |
| 17 | +~~~jsx {} |
| 18 | +triggers?: Array<{ |
| 19 | + trigger: string, |
| 20 | + data: Array<{ id?: string | number; label?: string; url?: string }> |
| 21 | + | ((query: string) => |
| 22 | + Array<{ id?: string | number; label?: string; url?: string }> |
| 23 | + | Promise<Array<{ id?: string | number; label?: string; url?: string }>>), |
| 24 | + showTrigger?: boolean, |
| 25 | + action?: (item) => void |
| 26 | +}>; |
| 27 | +~~~ |
| 28 | + |
| 29 | +### Parameters |
| 30 | + |
| 31 | +Each entry of the `triggers` array accepts the following fields: |
| 32 | + |
| 33 | +- `trigger` - (required) the character that opens the suggestion dropdown (for example, `"@"`, `"#"`, `"/"`, `"$"`) |
| 34 | +- `data` - (required) the data source for the dropdown; can be an array, a sync function, or an async function. See [Data source forms](#data-source-forms) |
| 35 | +- `showTrigger` - (optional) when `true` (default), RichText keeps the trigger character in the inserted token (for example, `@Alice`); when `false`, RichText inserts only `label` (for example, `Alice`) |
| 36 | +- `action` - (optional) a custom callback called when a user selects an item. When set, RichText removes the typed trigger text (the trigger character plus the query) and calls `action(item)` **instead of** inserting a token. The callback receives the picked item and can insert any content instead of the selected one. The `action` parameter takes priority over `showTrigger`, which has no effect when `action` is set. See [Custom action](#custom-action) |
| 37 | + |
| 38 | +### Data source forms |
| 39 | + |
| 40 | +* **Static array** — RichText filters the array automatically by matching the query against `label` (case-insensitive, `startsWith`): |
| 41 | + |
| 42 | +~~~jsx {3-7} |
| 43 | +new richtext.Richtext("#root", { |
| 44 | + triggers: [{ |
| 45 | + trigger: "@", |
| 46 | + data: [ |
| 47 | + { id: "alice", label: "Alice" }, |
| 48 | + { id: "bob", label: "Bob" } |
| 49 | + ] |
| 50 | + }] |
| 51 | +}); |
| 52 | +~~~ |
| 53 | + |
| 54 | +* **Sync function** — RichText calls your function with the current `query` string; you do the filtering and return the matching array: |
| 55 | + |
| 56 | +~~~jsx {3-6} |
| 57 | +new richtext.Richtext("#root", { |
| 58 | + triggers: [{ |
| 59 | + trigger: "#", |
| 60 | + data: query => tags.filter(t => |
| 61 | + t.label.toLowerCase().startsWith(query.toLowerCase()) |
| 62 | + ) |
| 63 | + }] |
| 64 | +}); |
| 65 | +~~~ |
| 66 | + |
| 67 | +* **Async function** — RichText calls your function with the current `query` string; return a `Promise` that resolves to the matching array. Useful for server-side search: |
| 68 | + |
| 69 | +~~~jsx {3-8} |
| 70 | +new richtext.Richtext("#root", { |
| 71 | + triggers: [{ |
| 72 | + trigger: "+", |
| 73 | + data: async query => { |
| 74 | + const res = await fetch(`/api/users?q=${encodeURIComponent(query)}`); |
| 75 | + const users = await res.json(); |
| 76 | + return users.map(u => ({ id: String(u.id), label: u.name, url: u.website })); |
| 77 | + } |
| 78 | + }] |
| 79 | +}); |
| 80 | +~~~ |
| 81 | + |
| 82 | +### Suggestion item fields |
| 83 | + |
| 84 | +Each item in `data` (or each item returned by a function) has the following fields: |
| 85 | + |
| 86 | +- `id` - (optional) unique identifier saved on the inserted token. If omitted, RichText generates an ID automatically |
| 87 | +- `label` - (optional) the text shown in the dropdown and inserted into the document. Required only for the default rendering; with a custom [`triggerTemplate`](api/config/trigger-template.md) you can render items from other fields (for example, `template(({ data }) => data.id)`) and omit `label` |
| 88 | +- `url` - (optional) URL associated with the item. RichText stores the URL as the inserted token's `href` attribute. `Ctrl+Click` on the token opens the link |
| 89 | + |
| 90 | +An item may also include any number of custom fields beyond `id`, `label`, and `url` (for example, `code` for an emoji, or `image` and `name` for an avatar). These extra fields are passed through to the [`triggerTemplate`](api/config/trigger-template.md) callback and to the `action` callback. |
| 91 | + |
| 92 | +### Rendered token |
| 93 | + |
| 94 | +When a user selects an item in the dropdown, RichText inserts a non-editable token element into the document: |
| 95 | + |
| 96 | +~~~html {} |
| 97 | +<a data-token="@" data-token-id="alice" href="mailto:alice@example.com">@Alice</a> |
| 98 | +~~~ |
| 99 | + |
| 100 | +- `@` (in `data-token="@"`) - the item's `trigger` |
| 101 | +- `alice` (in `data-token-id="alice"`) - the item's `id` |
| 102 | +- `mailto:alice@example.com` (in `href="mailto:alice@example.com"`) - the item's `url` |
| 103 | +- `@Alice` - the combination of `trigger` and `label`; with `showTrigger: false` it would be just `Alice` |
| 104 | + |
| 105 | +Use the `data-token` and `data-token-id` attributes to target tokens with CSS, for example, to highlight all mentions of a user: |
| 106 | + |
| 107 | +~~~css {} |
| 108 | +.wx-editor-content a[data-token="@"][data-token-id="alice"] { |
| 109 | + background: #fb8500; |
| 110 | + color: #fff; |
| 111 | +} |
| 112 | +~~~ |
| 113 | + |
| 114 | +### Custom action |
| 115 | + |
| 116 | +By default, when a user picks an item, RichText inserts the item into the document as a token. Set the `action` parameter to run your code instead: RichText removes the typed trigger string (the trigger character and the query) and calls the `action(item)` callback with the picked item. No token is inserted, so you can decide what to add to the document (or run your custom code). The `action` parameter takes priority over `showTrigger`. When `action` is set, `showTrigger` is ignored. |
| 117 | + |
| 118 | +#### Add emoji |
| 119 | + |
| 120 | +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: |
| 121 | + |
| 122 | +~~~jsx {8,12} |
| 123 | +const { template, Richtext } = richtext; |
| 124 | + |
| 125 | +const editor = new Richtext("#root", { |
| 126 | + triggers: [ |
| 127 | + { |
| 128 | + trigger: ":", |
| 129 | + data: emoji, // [{ id: "apple", label: "apple", code: "1F34E" }, ...] |
| 130 | + action: item => editor.insertValue(`<span>${emojiFromCode(item.code)} </span>`) |
| 131 | + } |
| 132 | + ], |
| 133 | + // render the emoji itself (not just its label) in the dropdown |
| 134 | + triggerTemplate: template(({ data }) => `${emojiFromCode(data.code)} ${data.label}`) |
| 135 | +}); |
| 136 | + |
| 137 | +function emojiFromCode(code) { |
| 138 | + return String.fromCodePoint(parseInt(code, 16)); |
| 139 | +} |
| 140 | +~~~ |
| 141 | + |
| 142 | +#### Group emoji by categories |
| 143 | + |
| 144 | +When the `data` parameter is a function, you are not limited to the built-in `label` matching. You can run your own filtering and keep category headers in the dropdown. Add header items that include a `label` field and do not include `code`. The `data` function first finds the emoji that match the query, then returns emoji together with the headers of the categories that still have matches: |
| 145 | + |
| 146 | +~~~jsx {18-26,31-33,41} |
| 147 | +const { template, Richtext } = richtext; |
| 148 | + |
| 149 | +// header items carry no `code` field; emoji items include one |
| 150 | +const emoji = [ |
| 151 | + { id: "$smileys", label: "Smileys", category: 1 }, // category |
| 152 | + { id: "grinning", label: "grinning", code: "1F600", category: 1 }, |
| 153 | + { id: "smile", label: "smile", code: "1F604", category: 1 }, |
| 154 | + { id: "$animals", label: "Animals", category: 2 }, // category |
| 155 | + { id: "dog", label: "dog", code: "1F436", category: 2 }, |
| 156 | + { id: "cat", label: "cat", code: "1F431", category: 2 } |
| 157 | +]; |
| 158 | + |
| 159 | +const editor = new Richtext("#root", { |
| 160 | + triggers: [ |
| 161 | + { |
| 162 | + trigger: ":", |
| 163 | + data: query => { |
| 164 | + const matched = emoji.filter(item => |
| 165 | + item.code && |
| 166 | + item.label.toLowerCase().startsWith(query.toLowerCase().trim()) |
| 167 | + ); |
| 168 | + const categories = new Set(matched.map(item => item.category)); |
| 169 | + // keep matching emoji plus the headers of categories that still match |
| 170 | + return emoji.filter(item => |
| 171 | + item.code ? matched.includes(item) : categories.has(item.category) |
| 172 | + ); |
| 173 | + }, |
| 174 | + action: item => editor.insertValue(`<span>${emojiFromCode(item.code)} </span>`) |
| 175 | + } |
| 176 | + ], |
| 177 | + // render emoji rows normally and category headers in bold |
| 178 | + triggerTemplate: template(({ data }) => |
| 179 | + data.code ? `${emojiFromCode(data.code)} ${data.label}` : `<b>${data.label}</b>` |
| 180 | + ) |
| 181 | +}); |
| 182 | + |
| 183 | +function emojiFromCode(code) { |
| 184 | + return String.fromCodePoint(parseInt(code, 16)); |
| 185 | +} |
| 186 | + |
| 187 | +// headers have no `code` — ignore picks on them so they are never inserted |
| 188 | +editor.api.intercept("insert-token", ({ data }) => !!data.code); |
| 189 | +~~~ |
| 190 | + |
| 191 | +#### Add slash-style command menu |
| 192 | + |
| 193 | +You can use `action` to build a slash-style command menu (like `/` in Notion or Slack). Store a command name in each item's `id`, its options in a custom `config` field, and let the callback run it with [`api.exec`](api/internal/exec.md): |
| 194 | + |
| 195 | +~~~jsx {13} |
| 196 | +// each item stores an api.exec action name in `id` and its parameters in `config` |
| 197 | +const commands = [ |
| 198 | + { id: "set-text-style", label: "Heading 1", config: { tag: "h1" } }, |
| 199 | + { id: "insert-list", label: "Bulleted list", config: { type: "bulleted" } }, |
| 200 | + { id: "insert-line", label: "Divider" } // no config → `|| {}` applies |
| 201 | +]; |
| 202 | + |
| 203 | +const editor = new richtext.Richtext("#root", { |
| 204 | + triggers: [ |
| 205 | + { |
| 206 | + trigger: "/", |
| 207 | + data: commands, |
| 208 | + action: item => editor.api.exec(item.id, item.config || {}) |
| 209 | + } |
| 210 | + ] |
| 211 | +}); |
| 212 | +~~~ |
| 213 | + |
| 214 | +### Example |
| 215 | + |
| 216 | +The following example sets up two triggers: `@` for mentions (each item carries a `url` that becomes the token's `href`) and `#` for tags (label only): |
| 217 | + |
| 218 | +~~~jsx {4,11} |
| 219 | +new richtext.Richtext("#root", { |
| 220 | + triggers: [ |
| 221 | + { |
| 222 | + trigger: "@", |
| 223 | + data: [ |
| 224 | + { id: "alice", label: "Alice", url: "mailto:alice@example.com" }, |
| 225 | + { id: "bob", label: "Bob", url: "mailto:bob@example.com" } |
| 226 | + ] |
| 227 | + }, |
| 228 | + { |
| 229 | + trigger: "#", |
| 230 | + data: [ |
| 231 | + { id: "css", label: "CSS" }, |
| 232 | + { id: "html", label: "HTML" } |
| 233 | + ] |
| 234 | + } |
| 235 | + ] |
| 236 | +}); |
| 237 | +~~~ |
| 238 | + |
| 239 | +**Change log:** The property was added in v2.1 |
| 240 | + |
| 241 | +**Related articles:** [Mentions and tags](guides/mentions_and_tags.md) |
0 commit comments