Docs Editor Model/Schema Cases Scenarios Tips Playground Coverage

Drag & Drop

Comprehensive guide to drag-and-drop operations in contenteditable elements, including event handling, file drops, browser differences, and mobile considerations.

Overview

Drag-and-drop operations in contenteditable elements involve several events and APIs. The HTML5 Drag and Drop API works with contenteditable, but behavior can be inconsistent across browsers, especially when dragging text within the same contenteditable region or handling file drops.

Key Concepts

  • Drag Events: dragstart, drag, dragend
  • Drop Events: dragover, dragenter, dragleave, drop
  • DataTransfer API: Access to dragged data, files, and drop effects
  • beforeinput: insertFromDrop inputType for intercepting drops
  • deleteByDrag: deleteByDrag inputType when content is dragged out

Basic Drag & Drop

Setting up basic drag-and-drop requires handling several events. The key is preventing default behavior and managing the DataTransfer object. 

// Basic drag and drop setup
const editor = document.querySelector('[contenteditable]');

// Make content draggable
editor.addEventListener('dragstart', (e) => {
  const selection = window.getSelection();
  if (selection.rangeCount > 0) {
    const range = selection.getRangeAt(0);
    const selectedText = range.toString();
    
    // Set drag data
    e.dataTransfer.setData('text/plain', selectedText);
    e.dataTransfer.setData('text/html', range.cloneContents());
    e.dataTransfer.effectAllowed = 'move'; // or 'copy', 'copyMove'
  }
});

// Handle drop
editor.addEventListener('drop', (e) => {
  e.preventDefault();
  const data = e.dataTransfer.getData('text/plain');
  // Insert data at drop position
});

// Prevent default drag behavior
editor.addEventListener('dragover', (e) => {
  e.preventDefault();
  e.dataTransfer.dropEffect = 'move';
});

⚠️ Prevent Default Behavior

Always call e.preventDefault() in dragover and drop events. Without this, the browser's default drop behavior will occur, which may not be what you want.

Dragging Within contenteditable

Dragging selected text within the same contenteditable region can be problematic. The browser may copy instead of move, or the drop position may not match the visual indicator. 

// Dragging text within contenteditable
const editor = document.querySelector('[contenteditable]');

let draggedRange = null;

editor.addEventListener('dragstart', (e) => {
  const selection = window.getSelection();
  if (selection.rangeCount > 0) {
    draggedRange = selection.getRangeAt(0).cloneRange();
    const html = draggedRange.cloneContents();
    
    e.dataTransfer.setData('text/html', html.innerHTML);
    e.dataTransfer.effectAllowed = 'move';
  }
});

editor.addEventListener('drop', (e) => {
  e.preventDefault();
  
  if (!draggedRange) return;
  
  // Get drop position
  const selection = window.getSelection();
  if (selection.rangeCount === 0) return;
  
  const dropRange = selection.getRangeAt(0);
  
  // Delete original content
  draggedRange.deleteContents();
  
  // Insert at drop position
  const fragment = draggedRange.extractContents();
  dropRange.insertNode(fragment);
  
  draggedRange = null;
});

⚠️ Inconsistent Behavior

In Chrome on macOS, dragging text within contenteditable sometimes results in copying instead of moving. The drop position may not match the visual indicator, and the original selection may remain visible after the drop. You must manually handle deletion of the original content.

Best Practices for Internal Dragging

  • Save the dragged range in dragstart for later deletion
  • Manually delete the original content in drop event
  • Use effectAllowed: 'move' to indicate moving behavior
  • Clear selection after drop to avoid visual artifacts

Dropping Into contenteditable

When dropping content into a contenteditable element, you can use either the drop event or the beforeinput event with insertFromDrop inputType.

Using drop Event

// Calculating drop position
editor.addEventListener('drop', (e) => {
  e.preventDefault();
  
  // Get mouse position
  const x = e.clientX;
  const y = e.clientY;
  
  // Find element at position
  const elementBelow = document.elementFromPoint(x, y);
  
  // Get range at position
  const range = document.caretRangeFromPoint(x, y);
  
  if (range) {
    // Insert at this position
    const data = e.dataTransfer.getData('text/plain');
    range.insertNode(document.createTextNode(data));
  }
});

Using beforeinput Event

// Using beforeinput for drop handling
const editor = document.querySelector('[contenteditable]');

editor.addEventListener('beforeinput', (e) => {
  if (e.inputType === 'insertFromDrop' && e.dataTransfer) {
    e.preventDefault();
    
    // Get dropped data
    const html = e.dataTransfer.getData('text/html');
    const text = e.dataTransfer.getData('text/plain');
    const files = e.dataTransfer.files;
    
    // Handle based on data type
    if (files.length > 0) {
      // Handle files
      handleFileDrop(files);
    } else if (html) {
      // Handle HTML
      insertHTML(html);
    } else if (text) {
      // Handle plain text
      insertText(text);
    }
  }
});

Which to Use?

  • beforeinput: Better for intercepting and customizing drop behavior, similar to paste handling
  • drop: More control over drop position calculation and file handling
  • Both: Can use both - handle in beforeinput and fallback to drop if needed

File Drag & Drop

Dropping files into contenteditable requires special handling. Files can be images, text files, or other types. Access files via dataTransfer.files. 

// File drag and drop
const editor = document.querySelector('[contenteditable]');

editor.addEventListener('dragover', (e) => {
  e.preventDefault();
  // Check if files are being dragged
  if (e.dataTransfer.types.includes('Files')) {
    e.dataTransfer.dropEffect = 'copy';
  }
});

editor.addEventListener('drop', async (e) => {
  e.preventDefault();
  
  const files = Array.from(e.dataTransfer.files);
  
  for (const file of files) {
    if (file.type.startsWith('image/')) {
      // Handle image
      const reader = new FileReader();
      reader.onload = (event) => {
        const img = document.createElement('img');
        img.src = event.target.result;
        
        // Insert image at drop position
        const selection = window.getSelection();
        if (selection.rangeCount > 0) {
          const range = selection.getRangeAt(0);
          range.insertNode(img);
        }
      };
      reader.readAsDataURL(file);
    } else if (file.type === 'text/plain') {
      // Handle text file
      const text = await file.text();
      const selection = window.getSelection();
      if (selection.rangeCount > 0) {
        const range = selection.getRangeAt(0);
        range.insertNode(document.createTextNode(text));
      }
    }
  }
});

⚠️ File Drop Limitations

In Safari on macOS, file drag and drop may not work correctly in contenteditable. Drop events may not fire for files, and file content may not be accessible. The default paste behavior may interfere. Test thoroughly on Safari.

File Handling Best Practices

  • Check e.dataTransfer.types to detect files before processing
  • Use FileReader API for reading file content
  • Handle images by creating <img> elements with data URLs
  • For text files, use file.text() or FileReader
  • Validate file types and sizes before processing

DataTransfer API

The DataTransfer API provides access to dragged data, files, and drop effects. Understanding its properties and methods is crucial for implementing drag-and-drop. 

// Accessing DataTransfer properties
editor.addEventListener('drop', (e) => {
  const dt = e.dataTransfer;
  
  // Available data types
  console.log(dt.types); // ['text/plain', 'text/html', 'Files']
  
  // Get data by type
  const plainText = dt.getData('text/plain');
  const html = dt.getData('text/html');
  
  // Files
  const files = Array.from(dt.files);
  
  // Effect allowed (from dragstart)
  console.log(dt.effectAllowed); // 'move', 'copy', 'copyMove', etc.
  
  // Drop effect
  console.log(dt.dropEffect); // 'move', 'copy', 'link', 'none'
});

DataTransfer Properties

  • types: Array of data types available (e.g., ['text/plain', 'text/html', 'Files'])
  • files: FileList of dropped files (read-only)
  • effectAllowed: Allowed drag effect set in dragstart ('move', 'copy', 'copyMove', 'link', etc.)
  • dropEffect: Current drop effect ('move', 'copy', 'link', 'none')
  • items: DataTransferItemList for accessing drag data

DataTransfer Methods

  • setData(type, data): Set drag data (only in dragstart)
  • getData(type): Get drag data (only in drop)
  • clearData(type?): Clear drag data (only in dragstart)
  • setDragImage(image, x, y): Set custom drag image

Platform-Specific Issues & Edge Cases

Browser-Specific Behavior

Chrome/Edge

  • Internal Dragging: Dragging text within contenteditable may copy instead of move
  • Drop Position: Drop position may not match visual indicator
  • Selection Artifacts: Original selection may remain visible after drop
  • File Handling: Generally works well for file drops

Firefox

  • Better Internal Dragging: Generally better support for dragging within contenteditable
  • HTML Stripping: May strip or modify HTML structure more aggressively when dropping
  • File Handling: File drop behavior may differ from Chrome

Safari

  • File Drop Issues: File drag and drop may not work correctly in contenteditable
  • Drop Events: Drop events may not fire for files
  • Mobile Behavior: Drag-and-drop behavior differs significantly on mobile

OS & Device-Specific Behavior

Desktop

  • Mouse Interaction: Standard mouse-based drag-and-drop works, but behavior varies
  • Modifier Keys: Ctrl/Cmd key may change behavior (copy vs move)

Mobile

  • Touch Interaction: Touch-based drag-and-drop may not work the same way as mouse-based
  • Limited Support: Some mobile browsers may not support insertFromDrop inputType
  • File Drops: File dropping from external apps may require special handling
  • Long Press: Long press may trigger different behavior than drag

General Edge Cases

  • Nested contenteditable: Dragging between nested contenteditable regions may cause issues
  • contenteditable="false": Dragging from or to non-editable areas within contenteditable may not work
  • IME Composition: Dragging during IME composition may cancel composition or cause issues
  • Undo/Redo: Drag-and-drop operations may not be properly integrated with undo/redo stack
  • Selection State: Selection state may be inconsistent after drag operations

Best Practices

  • Always Prevent Default: Call e.preventDefault() in dragover and drop events
  • Save Dragged Range: When dragging within contenteditable, save the range in dragstart for later deletion
  • Use beforeinput When Possible: beforeinput with insertFromDrop provides better integration with other input handling
  • Handle Files Separately: Check for files in dataTransfer.types and handle them appropriately
  • Calculate Drop Position: Use document.caretRangeFromPoint() or elementFromPoint() to find drop position
  • Clear Selection After Drop: Clear selection after drop to avoid visual artifacts
  • Test Across Browsers: Drag-and-drop behavior varies significantly - test on Chrome, Firefox, Safari, and mobile browsers
  • Provide Visual Feedback: Show visual feedback during drag (e.g., highlight drop zones, change cursor)
  • Handle Errors: File reading and data access may fail - handle errors gracefully

Related Resources