Skip to content

[lexical-playground] Feature: Add file attachment support with drag & drop functionality #7895

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 11 commits into
base: main
Choose a base branch
from
Open

[lexical-playground] Feature: Add file attachment support with drag & drop functionality #7895

wants to merge 11 commits into from

Conversation

Yjason-K
Copy link

@Yjason-K Yjason-K commented Oct 1, 2025 •
edited
Loading

Description

Current behavior:

  • The lexical playground editor only supports text, images, and other basic content types
  • No built-in support for file attachments or document uploads
  • Users cannot attach files like PDFs, Word documents, or other file types to their content

Changes being added:

  • AttachmentNode: New decorator node for handling file attachments with metadata (name, size, type, URL)
  • AttachmentComponent: React component for rendering attachment nodes with file type icons and interaction controls
  • AttachmentPlugin: Plugin providing drag & drop file upload, file insertion commands, and attachment management
  • File validation: Support for multiple file types (PDF, Office docs, images, videos, audio) with 3MB size limit
  • Serialization support: Base64 conversion for proper attachment persistence and export
  • UI integration: Toolbar button with file upload dialog and attachment preview
  • Comprehensive testing: E2E tests covering drag & drop, file validation, and attachment interactions

The implementation includes proper cleanup of object URLs, keyboard navigation support, and responsive styling that matches the playground theme.

Test plan

Before

  • Users could only add text, images, and basic content to the editor
  • No file attachment capabilities
  • Limited content types supported

After

File Upload Dialog:

  • Click attachment button in toolbar opens file selection dialog
  • File preview shows metadata (name, size, type) before insertion
  • Validation prevents oversized files (>3MB) and unsupported types

Drag & Drop Functionality:

  • Drag files directly into editor to create attachment nodes
  • Visual feedback during drag operations
  • Automatic file type detection and validation

Attachment Display:

  • File type icons for different formats (PDF, Word, Excel, etc.)
  • File metadata display (name, size)
  • Hover effects and selection states
  • Delete functionality with keyboard support

Serialization & Persistence:

  • Attachments properly serialize to/from JSON with base64 data
  • DOM export/import maintains attachment data
  • Object URL cleanup prevents memory leaks

Supported File Types:

  • Documents: PDF, Word (.doc/.docx), Excel (.xls/.xlsx), PowerPoint (.ppt/.pptx)
  • Images: JPEG, PNG, GIF, WebP
  • Videos: MP4, AVI, QuickTime
  • Audio: MP3, WAV, FLAC
  • Archives: ZIP, RAR
  • Text: TXT, CSV

E2E Test Coverage:

  • ✅ File upload via dialog
  • ✅ Drag & drop functionality
  • ✅ File type validation
  • ✅ Size limit enforcement
  • ✅ Attachment deletion
  • ✅ Keyboard navigation
  • ✅ Serialization/deserialization
attachment-plugin-test attachment-plugin-floating-toolbar
attachment.mov

Yjason-K added 11 commits October 1, 2025 15:52
@Yjason-K
[lexical][lexical-playground] Feature: add FilePreview component - re…
1b97aed 
…usable file info display

- Add FilePreview component for showing file metadata
- Display file name, size, and type information
- Include CSS styling for consistent appearance
@Yjason-K
[lexical][lexical-playground] Feature: add AttachmentNode - core atta…
0a29cdc 
…chment node implementation

- Implement DecoratorNode for file attachments with metadata (name, size, type, data)
- Add base64 ↔ object URL conversion utilities for serialization
- Support DOM import/export with data attributes
- Include comprehensive serialization/deserialization logic
- Add getter/setter methods for all attachment properties
@Yjason-K
[lexical][lexical-playground] Feature: add AttachmentComponent - UI c…
618b06f 
…omponent for attachment display

- Add React component for rendering attachment nodes
- Implement file type icon mapping and display
- Add selection handling and keyboard navigation
- Support attachment deletion and interaction
- Include floating UI for attachment actions
@Yjason-K
[lexical][lexical-playground] Feature: add AttachmentPlugin - drag & …
5f17cd8 
…drop and file insertion

- Add plugin for handling file attachments in editor
- Implement drag & drop file upload functionality
- Support file insertion via commands and dialog
- Add file validation and size limits (3MB)
- Handle various file types and formats
- Include attachment URL cleanup on editor destroy
@Yjason-K
[lexical][lexical-playground] Feature: register AttachmentNode in pla…
452c06d 
…yground nodes

- Add AttachmentNode to PlaygroundNodes array
- Enable attachment functionality in editor
@Yjason-K
[lexical][lexical-playground] Feature: integrate AttachmentPlugin int…
1cb5ca7 
…o playground editor

- Add AttachmentPlugin to Editor component
- Enable attachment functionality in playground editor
@Yjason-K
[lexical][lexical-playground] Feature: add attachment button to toolbar
e0a0f77 
- Add paperclip icon for attachment functionality
- Integrate attachment insertion dialog in toolbar
- Add UI controls for file upload
@Yjason-K
[lexical][lexical-playground] Style: add attachment node styling and …
28d0562 
…theme updates

- Add CSS classes for attachment node styling
- Update playground theme for attachment display
- Include responsive design for attachment components
@Yjason-K
[lexical][lexical-playground] Feature: add attachment testing utilities
2126ad8 
- Add helper functions for attachment e2e testing
- Include file upload simulation utilities
- Add attachment interaction test helpers
@Yjason-K
[lexical][lexical-playground] Feature: add comprehensive e2e tests fo…
d40b2d7 
…r attachment functionality

- Add Playwright tests for attachment drag & drop workflow
- Test file upload dialog and attachment display
- Verify attachment deletion and keyboard navigation
- Add file type validation and size limit tests
- Include attachment serialization/deserialization tests
@Yjason-K
[lexical][lexical-playground] Feature: integrate attachment support i…
ff97b6b 
…n DragDropPastePlugin

- Add attachment file type validation alongside existing image types
- Support drag & drop for documents (PDF, Office files), archives, text, video, and audio files
- Implement 3MB size limit validation for attachment files
- Add file type inference from extension when MIME type is unavailable
- Prioritize image insertion over attachment for image files
- Include comprehensive file type mapping for attachment formats
- Handle unsupported file types with appropriate warnings
@vercel Vercel
Copy link

vercel bot commented Oct 1, 2025 •
edited
Loading

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

Project Deployment Preview Comments Updated (UTC)
lexical Ready Ready Preview Comment Oct 1, 2025 8:14am
lexical-playground Ready Ready Preview Comment Oct 1, 2025 8:14am

@meta-cla meta-cla bot added the CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. label Oct 1, 2025
@ivailop7 ivailop7 added the extended-tests Run extended e2e tests on a PR label Oct 1, 2025
@etrepum
Copy link
Collaborator

etrepum commented Oct 1, 2025

File uploads encoded as base64 isn't really a very good idea. It's done for images just for demonstration purposes, but in order to support attachments (and images) in any real production capacity you would really need to have some server-side code or service provider (amazon s3, cloudflare r2, etc.) storing those files and the document should only store the URLs. My concern about adding more examples of what not to do will lead to more bad code in people's applications.

@Yjason-K
Copy link
Author

Yjason-K commented Oct 2, 2025

@etrepum
Thanks for the feedback—I understand your point and I’m removing the base64 approach.
I fully agree that in production files should be uploaded to a server/storage provider and referenced by URL only. To align with that, I’ll add an abstracted AttachmentStore interface so developers can plug in a real backend with the same API.
For the playground demo (which resets on reload), I’ll keep it server-free and generate session-scoped object URLs (blob:) from uploaded files, so the document still stores URLs only during the session (no base64).
To avoid encouraging bad practices, I’ll limit the demo to a few formats (eg. PDF, DOCX, Markdown), enforce MIME/size checks, and include clear “demo only” notes, plus Export/Import and a “Clear storage” action.
If you see a better direction, I’m glad to follow it :)

@vadimkantorov
Copy link

vadimkantorov commented Oct 7, 2025 •
edited
Loading

One useful primitive that I found when using Lexical for editing pages on GitHub-backed site is:

  • having blog:// urls during document editing until the file/image is committed yet to the server storage (this means maintaining a map between local<>remote urls, having an util for committing the uncommitted files and updating their urls, providing an util for converting a relative path to absolute https-url)
  • having support for relative urls used in images/attachments: like /uploads/myimage.jpg, and having the base url prefix be attached only when rendering to the img tag (unfortunately we cannot have a special <base> tag just for images)

Like so, content with attached images/files can be nicely edited in markdown and conversion markdown <> visual representation

I named this "ImageRegistry", but maybe this concept could be fused into AttachmentStore

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@zurfyx zurfyx Awaiting requested review from zurfyx zurfyx is a code owner

@acywatson acywatson Awaiting requested review from acywatson acywatson is a code owner

@Fetz Fetz Awaiting requested review from Fetz Fetz is a code owner

@ivailop7 ivailop7 Awaiting requested review from ivailop7 ivailop7 is a code owner

@Sahejkm Sahejkm Awaiting requested review from Sahejkm Sahejkm is a code owner

@potatowagon potatowagon Awaiting requested review from potatowagon potatowagon is a code owner

@takuyakanbr takuyakanbr Awaiting requested review from takuyakanbr takuyakanbr is a code owner

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
CLA Signed This label is managed by the Facebook bot. Authors need to sign the CLA before a PR can be reviewed. extended-tests Run extended e2e tests on a PR
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@Yjason-K @etrepum @vadimkantorov @ivailop7