🖱️ Chapter 47: HTML5 Drag and Drop API

dropEffect and effectAllowed

Mastering the drag-and-drop handshake contract, OS cursor glyphs, and action negotiations for Copy, Move, Link, and None.

LEARNING OBJECTIVES ⌵

Understand the architectural relationship and handshake contract between effectAllowed and dropEffect.
Configure effectAllowed on the Drag Source during dragstart.
Negotiate and set dropEffect on the Drop Target during dragover.
Identify the operating system cursor glyphs associated with copy, move, link, and none.
Implement dynamic modifier key detection (e.g., Ctrl for Copy, Shift for Move).

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine an international trade negotiation between an Exporter (Drag Source) and an Importer (Drop Target).

The Exporter’s Manifesto (effectAllowed): When shipping cargo from the factory, the exporter stamps an export license:
- "This container can be Sold (Copy), Relocated (Move), or Leased (Link)" (effectAllowed = "all").
- Alternatively, for a unique original painting: "This can ONLY be Relocated (Move); copies are strictly forbidden!" (effectAllowed = "move").
The Importer’s Customs Station (dropEffect): When the cargo arrives at the destination port, the customs officer checks their local regulations:
- "We are a photocopy archive; we only accept Copies" (dropEffect = "copy").
- If the exporter's license allows copy, the transaction is approved! The OS cursor changes to a green plus badge [+].
- If the exporter stated effectAllowed = "move" (no copies allowed), but the customs officer demands dropEffect = "copy", the handshake fails. The cursor immediately displays a red crossed-out circle [🚫] (no-drop), and the drop cannot proceed.

+---------------------------+                      +---------------------------+
|    DRAG SOURCE ELEMENT    |                      |    DROP TARGET ELEMENT    |
| (dragstart)               |                      | (dragover)                |
|                           |                      |                           |
| effectAllowed:            | ===== Handshake ===> | dropEffect:               |
| - 'copy'                  |       Contract       | - 'copy'                  |
| - 'move'                  |                      | - 'move'                  |
| - 'link'                  |                      | - 'link'                  |
| - 'all'                   |                      | - 'none'                  |
+---------------------------+                      +---------------------------+
                                          |
                                          v
               +-----------------------------------------------------+
               |              BROWSER OS CURSOR OUTPUT               |
               |  - 'copy': Cursor with [+] badge                    |
               |  - 'move': Standard pointer / Drag icon             |
               |  - 'link': Cursor with curved shortcut arrow [↗]    |
               |  - 'none': Crossed circle / Prohibited icon [🚫]    |
               +-----------------------------------------------------+

Technical Deep Dive & Specifications

The Permitted Values Matrix

The browser enforces a strict mathematical compatibility matrix between the source's effectAllowed and the target's dropEffect.

`effectAllowed` Values (Set in `dragstart`)

Must be configured when initiating the drag. Setting it in subsequent events has no effect.

Value	Allowed Operations at Target
`'none'`	The item may not be dropped anywhere.
`'copy'`	Only `'copy'` drop effect is permitted.
`'move'`	Only `'move'` drop effect is permitted.
`'link'`	Only `'link'` drop effect is permitted.
`'copyMove'`	Either `'copy'` or `'move'` is permitted.
`'copyLink'`	Either `'copy'` or `'link'` is permitted.
`'linkMove'`	Either `'link'` or `'move'` is permitted.
`'all'`	Any operation (`copy`, `move`, `link`) is permitted.
`'uninitialized'` (default)	Treated identically to `'all'`.

`dropEffect` Values (Set in `dragover`)

Configured on the target to tell the browser which single operation will be performed if the drop occurs here.

Value	OS Cursor Visual Feedback	Meaning
`'copy'`	Pointer with a `+` badge	A copy of the source item will be created at the target.
`'move'`	Standard drag arrow / hand	The source item will be removed from old location and placed here.
`'link'`	Pointer with an alias arrow (↗)	A shortcut or reference link to the source item will be created.
`'none'`	Forbidden sign (🚫 / Circle-slash)	The drop is not allowed here; dropping triggers cancellation.

Compatibility & Handshake Rules

If a drop target sets dropEffect = 'copy', but the source declared effectAllowed = 'move', the browser detects an incompatible contract. The dropEffect is automatically reset to 'none', rendering the forbidden cursor.

                     +---------------------------------------+
                     | Target sets: dropEffect = 'copy'      |
                     +---------------------------------------+
                                        |
                   Is 'copy' permitted by effectAllowed?
                                       / \
                                     YES  NO
                                     /      \
               [ Show (+) Copy Cursor ]    [ Override to 'none' (🚫) ]

[!IMPORTANT] dropEffect is purely an instruction to the browser's UI engine to render the correct operating system cursor. Setting dropEffect = 'copy' does not clone DOM nodes automatically! You must write the JavaScript logic inside the drop event to handle cloning vs. moving.

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Line 77 (e.dataTransfer.effectAllowed = 'all'): Authorizes any destination zone to perform either copy, move, or link.
Line 86 (e.dataTransfer.dropEffect = effect): In the dragover handler, the target assigns its desired effect ('copy', 'move', or 'link'). The browser updates the OS mouse pointer instantaneously.
Line 99–112 (if (effect === 'copy') ... else if (effect === 'move')): Demonstrates that the developer must implement the actual business logic for copying vs. moving. The browser only updates the cursor.

Expected Browser Render Output

Hovering over Zone 1 renders a + badge next to the pointer. Over Zone 2, standard move cursor. Over Zone 3, alias link arrow.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Lesson 47.4: dropEffect & effectAllowed</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      background: #0f172a;
      color: #f8fafc;
      padding: 2rem;
    }
    .layout {
      display: grid;
      grid-template-columns: 240px repeat(3, 1fr);
      gap: 1.5rem;
      margin-top: 1.5rem;
    }
    .panel {
      background: #1e293b;
      border: 2px dashed #475569;
      border-radius: 8px;
      padding: 1rem;
      min-height: 240px;
    }
    .panel.over {
      border-color: #38bdf8;
      background: #1e3a5f;
    }
    .file-card {
      background: #3b82f6;
      padding: 1rem;
      border-radius: 6px;
      cursor: grab;
      user-select: none;
      font-weight: 500;
    }
    .badge {
      display: inline-block;
      font-size: 0.75rem;
      padding: 2px 6px;
      border-radius: 4px;
      background: rgba(0, 0, 0, 0.3);
      margin-top: 6px;
    }
    .dest-list {
      list-style: none;
      padding: 0;
      margin-top: 10px;
      font-size: 0.85rem;
    }
    .dest-list li {
      padding: 6px;
      background: #334155;
      border-radius: 4px;
      margin-bottom: 6px;
    }
  </style>
</head>
<body>
  <h1>Operation Effects Handshake</h1>
  <p>Drag the file and observe how the OS cursor changes over each target zone:</p>

<div class="layout">
    <div class="panel">
      <h3>Source Repository</h3>
      <div class="file-card" id="source-doc" draggable="true">
        📄 Financial_Q4.pdf
        <div class="badge">effectAllowed: all</div>
      </div>
    </div>

<div class="panel" id="zone-copy" data-effect="copy">
      <h3>1. Duplicate (Copy)</h3>
      <p style="font-size: 0.8rem; color: #94a3b8;">Shows [+] Cursor</p>
      <ul class="dest-list" id="copy-list"></ul>
    </div>

<div class="panel" id="zone-move" data-effect="move">
      <h3>2. Archive (Move)</h3>
      <p style="font-size: 0.8rem; color: #94a3b8;">Shows Move Cursor</p>
      <ul class="dest-list" id="move-list"></ul>
    </div>

<div class="panel" id="zone-link" data-effect="link">
      <h3>3. Shortcut (Link)</h3>
      <p style="font-size: 0.8rem; color: #94a3b8;">Shows (↗) Shortcut Cursor</p>
      <ul class="dest-list" id="link-list"></ul>
    </div>
  </div>

// 1. Set effectAllowed on dragstart
    doc.addEventListener('dragstart', (e) => {
      e.dataTransfer.setData('text/plain', 'Financial_Q4.pdf');
      // Allow any operation
      e.dataTransfer.effectAllowed = 'all';
    });

zones.forEach(zone => {
      const effect = zone.getAttribute('data-effect');

zone.addEventListener('dragover', (e) => {
        e.preventDefault();
        // Request specific cursor effect from the browser
        e.dataTransfer.dropEffect = effect;
        zone.classList.add('over');
      });

zone.addEventListener('dragleave', () => {
        zone.classList.remove('over');
      });

zone.addEventListener('drop', (e) => {
        e.preventDefault();
        zone.classList.remove('over');
        const filename = e.dataTransfer.getData('text/plain');
        const list = zone.querySelector('.dest-list');

if (effect === 'copy') {
          const item = document.createElement('li');
          item.textContent = `📋 Copy of ${filename} (${Date.now()})`;
          list.appendChild(item);
        } else if (effect === 'move') {
          const item = document.createElement('li');
          item.textContent = `📦 Moved ${filename}`;
          list.appendChild(item);
          // Hide source to simulate a real move
          doc.style.display = 'none';
        } else if (effect === 'link') {
          const item = document.createElement('li');
          item.textContent = `🔗 Symlink -> ${filename}`;
          list.appendChild(item);
        }
      });
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

+------------------+  +------------------+  +------------------+  +------------------+
| Source Repo      |  | 1. Duplicate     |  | 2. Archive       |  | 3. Shortcut      |
| [📄 Financial]   |  | (Cursor: [+])    |  | (Cursor: Move)   |  | (Cursor: [↗])    |
+------------------+  +------------------+  +------------------+  +------------------+

🏋️ Hands-On Exercise

🎯 The Challenge: Dynamic Modifier Key Router

Instructions:

Create a draggable file element "Dataset_2026.csv".
Configure effectAllowed = 'copyMove' on dragstart.
Create a single drop container "Central Storage Depot".
In the container's dragover listener, inspect event.ctrlKey (or event.altKey):
- If the user is holding Ctrl, set dropEffect = 'copy' (showing + cursor).
- If no modifier key is held, set dropEffect = 'move' (showing Move cursor).
In the drop handler:
- If dropped as copy, append a "Copied Dataset" entry without removing the source.
- If dropped as move, append a "Moved Dataset" entry and remove the original source.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Modifier Key DnD Router</title>
  <style>
    body { font-family: sans-serif; background: #0f172a; color: white; padding: 20px; }
    .layout { display: flex; gap: 30px; }
    .box { width: 300px; min-height: 250px; background: #1e293b; padding: 15px; border-radius: 8px; border: 2px dashed #475569; }
    .file { background: #6366f1; padding: 12px; border-radius: 6px; cursor: grab; }
  </style>
</head>
<body>
  <h2>Hold [Ctrl] while dragging to Copy; Release to Move</h2>
  <div class="layout">
    <div class="box" id="source-box">
      <div class="file" id="data-file" draggable="true">📊 Dataset_2026.csv</div>
    </div>
    <div class="box" id="depot">
      <h3>Central Storage Depot</h3>
      <div id="depot-log"></div>
    </div>
  </div>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Modifier Key DnD Router</title>
  <style>
    body { font-family: sans-serif; background: #0f172a; color: white; padding: 20px; }
    .layout { display: flex; gap: 30px; }
    .box { width: 300px; min-height: 250px; background: #1e293b; padding: 15px; border-radius: 8px; border: 2px dashed #475569; transition: border-color 0.2s; }
    .box.over { border-color: #38bdf8; background: #1e3a5f; }
    .file { background: #6366f1; padding: 12px; border-radius: 6px; cursor: grab; user-select: none; }
    .log-item { background: #334155; padding: 8px; border-radius: 4px; margin-top: 8px; font-size: 0.9rem; }
  </style>
</head>
<body>
  <h2>Hold [Ctrl] while dragging to Copy; Release to Move</h2>
  <div class="layout">
    <div class="box" id="source-box">
      <div class="file" id="data-file" draggable="true">📊 Dataset_2026.csv</div>
    </div>
    <div class="box" id="depot">
      <h3>Central Storage Depot</h3>
      <div id="depot-log"></div>
    </div>
  </div>

  <script>
    const file = document.getElementById('data-file');
    const depot = document.getElementById('depot');
    const depotLog = document.getElementById('depot-log');

    file.addEventListener('dragstart', (e) => {
      e.dataTransfer.setData('text/plain', file.textContent.trim());
      e.dataTransfer.effectAllowed = 'copyMove';
    });

    depot.addEventListener('dragover', (e) => {
      e.preventDefault();
      depot.classList.add('over');
      // Dynamically select drop effect based on Ctrl key state
      if (e.ctrlKey) {
        e.dataTransfer.dropEffect = 'copy';
      } else {
        e.dataTransfer.dropEffect = 'move';
      }
    });

    depot.addEventListener('dragleave', () => {
      depot.classList.remove('over');
    });

    depot.addEventListener('drop', (e) => {
      e.preventDefault();
      depot.classList.remove('over');
      const filename = e.dataTransfer.getData('text/plain');
      const log = document.createElement('div');
      log.classList.add('log-item');

      if (e.ctrlKey || e.dataTransfer.dropEffect === 'copy') {
        log.textContent = `📋 [COPIED] ${filename}`;
        depotLog.appendChild(log);
      } else {
        log.textContent = `📦 [MOVED] ${filename}`;
        depotLog.appendChild(log);
        file.style.display = 'none'; // Remove from source
      }
    });
  </script>
</body>
</html>

Why this works:

Setting effectAllowed = 'copyMove' permits both operations.
The dragover listener inspects e.ctrlKey in real-time as the user presses or releases the key mid-drag, immediately toggling the OS cursor between Copy and Move.
In drop, the code checks e.dataTransfer.dropEffect to decide whether to delete or preserve the source node.

⚠️ Common Pitfalls

Configuring effectAllowed in dragover: effectAllowed can only be modified during dragstart. Setting it in any subsequent event (drag, dragover, drop) is silently ignored by the browser.
Assuming dropEffect Performs Automatic Clones: Developers often believe setting dropEffect = 'copy' automatically duplicates elements. It only updates the OS cursor glyph; you must explicitly execute element.cloneNode(true) or state updates in JavaScript.
Requesting an Disallowed Effect: If effectAllowed = 'move', and dropEffect = 'copy', the browser invalidates the operation, resets dropEffect to 'none', and presents a 🚫 cursor.

💡 Pro Tips

Mac vs. Windows Keyboard Modifiers: On Windows/Linux, the Ctrl key traditionally signifies Copy. On macOS, the Option (Alt) key signifies Copy, and Cmd (Meta) + Option signifies Link. Support both by checking e.ctrlKey || e.altKey.
Defensive Validation on Drop: Never trust e.dataTransfer.dropEffect alone on drop; always re-verify your application permissions and state model before committing destructive operations (like deleting the source card).

📌 Key Takeaways

effectAllowed is set on the Drag Source during dragstart to declare authorized operations.
dropEffect is set on the Drop Target during dragover to request a specific action from the browser.
The four primary effect types are: copy (+), move (standard pointer), link (↗), and none (🚫).
If dropEffect contradicts effectAllowed, the drop is canceled and the browser displays the forbidden cursor.
Inspecting modifier keys (event.ctrlKey, event.altKey) during dragover provides desktop-grade user ergonomics.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

In which drag lifecycle event MUST `event.dataTransfer.effectAllowed` be configured?

Topic: HTML Fundamentals

? Question 2 / 3

What cursor does the operating system display if a drop target sets `dropEffect = 'copy'` but the source declared `effectAllowed = 'move'`?

Topic: HTML Fundamentals

? Question 3 / 3

Does setting `e.dataTransfer.dropEffect = 'copy'` automatically clone the dragged DOM element into the drop target?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

The Permitted Values Matrix

effectAllowed Values (Set in dragstart)

dropEffect Values (Set in dragover)

Compatibility & Handshake Rules

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Dynamic Modifier Key Router

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

In which drag lifecycle event MUST event.dataTransfer.effectAllowed be configured?

What cursor does the operating system display if a drop target sets dropEffect = 'copy' but the source declared effectAllowed = 'move'?

Does setting e.dataTransfer.dropEffect = 'copy' automatically clone the dragged DOM element into the drop target?

`effectAllowed` Values (Set in `dragstart`)

`dropEffect` Values (Set in `dragover`)

In which drag lifecycle event MUST `event.dataTransfer.effectAllowed` be configured?

What cursor does the operating system display if a drop target sets `dropEffect = 'copy'` but the source declared `effectAllowed = 'move'`?

Does setting `e.dataTransfer.dropEffect = 'copy'` automatically clone the dragged DOM element into the drop target?