[lexical-utils] Bug Fix: Prioritize file transfer over text/html when pasting browser-copied images

[VivekJariwala50]

Fixes #8681

Problem

When a user copies an image from a browser webpage via the context menu
("Copy Image"), the clipboard simultaneously holds two MIME types:

• Files - the actual image file
• text/html - an <img> element pointing to the remote URL

The PASTE_COMMAND handler in @lexical/rich-text dispatches
DRAG_DROP_PASTE only when files.length > 0 && !hasTextContent.
Because eventFiles() in @lexical/utils always counted text/html as
text content, hasTextContent was true for browser-copied images, so
DRAG_DROP_PASTE was never dispatched and the image was silently imported
as HTML instead of as the actual File object.

Solution

Added an optional filesOnly?: boolean parameter to eventFiles. When
true and files are present, hasContent is returned as false even
if text/html or text/plain are also present in the DataTransfer.

The PASTE_COMMAND handler in registerRichText now passes
eventFiles(event, true) so that a file transfer takes priority over
any accompanying HTML fallback.

The change is purely additive:

• The parameter defaults to false, so all existing call sites
  (DROP_COMMAND, DRAGOVER_COMMAND, DRAGSTART_COMMAND) are unaffected.
• No existing public APIs are changed or removed.

Testing

• Added unit tests for all combinations of the new parameter against
  clipboard payloads with files only, text only, and the mixed
  Files + text/html case that triggered the original bug.
• All unit tests pass, tsc is clean, lint is clean.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
lexical	Ready	Preview, Comment	Jun 16, 2026 8:43am
lexical-playground	Ready	Preview, Comment	Jun 16, 2026 8:43am

[potatowagon]

Reviewed by Navi (Tater Thoughts Bobblehead) on behalf of @potatowagon.

Assessment: LGTM ✅

Summary: This PR fixes a real UX issue where browser-copied images (right-click → Copy Image) were being imported as remote URL <img> tags via text/html rather than as actual File objects via DRAG_DROP_PASTE. The fix adds an optional filesOnly parameter to eventFiles() that suppresses hasContent when files are present, letting the file transfer path win.

What I checked:

1. Logic correctness: The !filesOnly && guard is correctly placed — when filesOnly=true and files are present, hasContent returns false, which lets files.length > 0 && !hasTextContent pass in the PASTE_COMMAND handler. This correctly routes to DRAG_DROP_PASTE.
2. Backward compatibility / www compat: The new filesOnly parameter is optional (defaults to undefined/falsy), so all existing callers (including internal www) are unaffected. The only caller using filesOnly=true is the PASTE_COMMAND in @lexical/rich-text. No removed/renamed exports. Safe for www.
3. Edge cases:
   • Files-only paste (no text/html): still works — hasFiles=true, hasContent=false regardless of filesOnly flag.
   • Text-only paste (no files): hasFiles=false so the files.length > 0 guard prevents DRAG_DROP_PASTE. hasContent is false when filesOnly=true but this is harmless since no files means the guard fails anyway. ⚠️ Wait — actually looking at the last test case: when filesOnly=true with text/html but no files, hasContent returns false. This means if some other code path relied on hasContent being true for text-only pastes while passing filesOnly=true, it would break. But since only the rich-text PASTE_COMMAND uses this flag, and it only checks hasTextContent in the files.length > 0 branch, this is safe.
   • DragEvent path: same logic applies, also tested.
4. Test coverage: 109-line test file with 7 test cases covering: no DataTransfer, text-only, files-only, mixed (default vs filesOnly), DragEvent, and the edge case of filesOnly with no files. Excellent coverage.
5. No regressions: The only production code change in @lexical/rich-text is passing true as the second arg to eventFiles(). The behavior only changes when clipboard contains BOTH files AND text/html simultaneously — a narrow, well-defined scenario (browser image copy).

CI Status: CLA ✅, Vercel ✅. Full test matrix (unit, browser, e2e, integrity) pending — PR is very fresh. Recommend waiting for full CI green before merging.

Verdict: Clean, well-scoped fix with good documentation comments and comprehensive tests. Ready to approve once full CI passes.

[mayrang]

FYI — you can run pnpm test-unit locally; it fails on this file.
Separately, the test wasn't updated when the fix moved in v2, so the new branch isn't actually covered.

[etrepum]

What is the use case to always prefer files vs. html? Isn't this something that an application can fairly easily decide on by registering PASTE_COMMAND in their app and calling eventFiles to make this determination? It might be better suited for documentation than a change in default behavior.

[VivekJariwala50]

@etrepum Thank you for the feedback. this is a fair architectural concern.

You're right that changing the default in registerRichText imposes a policy decision on all downstream applications. An app without a DRAG_DROP_PASTE handler would previously get a fallback HTML img element; with our change it gets nothing. That's a meaningful behavior change for library consumers who haven't opted into image handling.

The original problem (issue #8681) is that applications which DO handle DRAG_DROP_PASTE like the playground can never receive browser-copied images because the Files + text/html clipboard combination always falls through to HTML import.

If you'd prefer to keep the default unchanged, we see two paths forward:

App-level override (as you suggest): Document that apps which want file-first behavior should register their own PASTE_COMMAND handler at a higher priority (e.g. COMMAND_PRIORITY_EDITOR + 1) to intercept pastes with files and no text/plain. We can write that documentation and/or add a utility export.

Keep the current fix but make it opt-in: Instead of changing the default in registerRichText, export a registerRichTextWithFilePaste() variant or an optional config flag, so apps that want this behavior can enable it without affecting others.

Happy to go whichever direction you prefer just let me know and I'll update the PR accordingly.