Lexical Editor Integration in the Prompt Editor#

Dify's prompt editor (web/app/components/base/prompt-editor/) is built on Lexical, Meta's extensible text editor framework. The editor is structured as a LexicalComposer that renders PromptEditorContent — a composition of Lexical plugins that handles rich block types (context, history, variables, workflow variables, agent output, etc.) and two typeahead pickers triggered by / and { 1.

Entry Points#

Typeahead Plugin System (ComponentPickerBlock)#

Both the slash picker (/) and brace picker ({) are instances of the same ComponentPickerBlock component, instantiated with different triggerString props 1. Either picker can be disabled via disableSlashPicker / disableBracePicker props on PromptEditorContent.

LexicalTypeaheadMenuPlugin Wiring#

ComponentPickerBlock wraps Lexical's LexicalTypeaheadMenuPlugin with three key props 2:

• triggerFn — calls checkForTriggerMatch (see below) on every keystroke to decide whether to open the menu.
• options — the flat list of PickerBlockMenuOption objects built by useOptions().
• menuRenderFn — renders the floating picker UI via Floating UI. Lexical's internal anchor positioning is intentionally bypassed with anchorClassName="z-50 translate-y-[calc(-100%-3px)]" 3.

The menu uses @floating-ui/react with offset, shift, and flip middleware for positioning 4. A blurHidden flag (toggled via BLUR_COMMAND / FOCUS_COMMAND) controls whether the picker renders when the editor loses focus 5.

Option Hooks#

useOptions() aggregates results from three sub-hooks 6:

• usePromptOptions — context, query, history, request URL blocks.
• useVariableOptions — per-variable PickerBlockMenuOption items; calls editor.dispatchCommand(INSERT_VARIABLE_VALUE_BLOCK_COMMAND, ...) on selection 7.
• useExternalToolOptions — same pattern for tools backed by externalToolBlockType.externalTools 8.

Workflow variables are kept separate in workflowVariableOptions and rendered via VarReferenceVars rather than the flat options list 9.

Trigger Matcher Customization#

The trigger function is defined in hooks.ts as useBasicTypeaheadTriggerMatch. It constructs a regex at call time from the trigger character and captures trailing text up to maxLength (default 75 characters for the component picker, 10).

Key design points:

1. Character class escaping — The trigger character is passed through escapeForCharacterClass (/[[\]\\^-]/g) before embedding it in a character class [${escapedTrigger}]. This handles the { trigger safely — { has no special meaning inside […].
2. Valid characters — The match pattern excludes the trigger character and newlines: [^${escapedTrigger}\n\r] 11.
3. Return shape — Returns { leadOffset, matchingString, replaceableString } or null when no match 12. matchingString is the text typed after the trigger; replaceableString includes the trigger.

ComponentPickerBlock wraps this in its own checkForTriggerMatch callback that stores the match in triggerMatchRef so insertion logic can access the last known match state 13.

Slash Trigger Boundary Behavior#

The slash picker relies on the requireTriggerBoundary option (introduced in PR #39768) to prevent the picker from reopening when the user clicks on existing slash characters in URLs, file paths, or other text. The boundary matcher ensures that slash commands only activate at the beginning of text or after whitespace, avoiding unwanted picker activation on path separators like https://example.com/path.

Special Character Handling & Known Issue#

The { Trigger and Plain-Text Braces#

The brace picker activates on any single { character (without a boundary requirement), which conflicts with common prompt patterns like {variable}, markdown link targets ({source_url}), or Jinja templates. The { trigger is safe at the regex-construction level (see above), but the queryString it captures is passed unsanitized into new RegExp(queryString, 'i') in useVariableOptions and useExternalToolOptions .

Crash: Regex Special Characters in Query String#

If a user types { followed by regex metacharacters (e.g., [, ], }, ), \), the filter call new RegExp(queryString, 'i') throws a SyntaxError, crashing the editor component 16.

Example trigger text: [Open manual]({source_url}) — after {, the typeahead captures source_url}) as queryString, which is an invalid regex pattern.

Fix pattern (identified in the issue): escape the query string before constructing the regex 16:

const escapeRegExp = (value: string) =>
  value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')

const regex = new RegExp(escapeRegExp(queryString), 'i')

This fix needs to be applied in two places: useVariableOptions line 180 and useExternalToolOptions line 256 in hooks.tsx.

Update Lifecycle (UpdateBlock)#

UpdateBlock enables programmatic editor replacement via event emitter 17:

• PROMPT_EDITOR_UPDATE_VALUE_BY_EVENT_EMITTER — parses a plain-text string via textToEditorState() and calls editor.setEditorState(), then marks all CustomTextNode instances dirty to trigger re-decoration.
• PROMPT_EDITOR_INSERT_QUICKLY — focuses the editor and inserts a / node to open the slash picker programmatically.

Reference Block Insertion#

When Agent roster reference blocks are inserted (via the slash picker in the Agent Configure prompt editor), a single trailing separator is added after the reference block and the caret is restored after it. This ensures proper spacing for continued text input.