Drag and drop

  • Revision slug: DragDrop/Drag_and_Drop
  • Revision title: Drag and drop
  • Revision id: 443697
  • Created:
  • Creator: kscarfone
  • Is current revision? No
  • Comment Fixed several typos.

Revision Content

Firefox and other Mozilla applications support a number of features for handling drag and drop. This allows the user to click and hold the mouse button down over an element, drag it to another location, and release the mouse button to drop the element there. A translucent representation of what is being dragged will follow the mouse pointer during the drag operation. The drop location may be a different application. Web sites, extensions, and XUL applications may make use of this functionality to customize what elements may be dragged, the drag feedback, as well as specify where elements may be dropped.

This section covers drag and drop in Firefox 3.5 (Gecko 1.9.1) and later. For the older API for Firefox 3.0 and earlier, which is not exposed to web pages, see the older API documentation.

Drag and drop basics

When a drag begins, a number of pieces of information may be provided:

  • the data to be dragged, which may be of a number of different formats. For example, textual data containing a string of text being dragged. For information about this, see Drag Data.
  • the drag feedback image which appears beside the mouse pointer during the drag operation. This image may be customized; however, most of the time, you would not specify this, and a default image will be generated based on the element where the mouse was pressed down. To learn more about drag feedback images, see Setting the Drag Feedback Image.
  • drag effects that are allowed. Three such effects are possible: copy to indicate that the data being dragged will be copied from its present location to the drop location, move to indicate that the data being dragged will be moved, and link to indicate that some form of relationship or connection will be created between the source and drop locations. During the drag operation, the drag effects may be modified to indicate that certain effects are allowed at certain locations. If allowed, a drop may occur at that location. See Drag Effects for more details.

Mozilla and Firefox support a number of features not in the standard drag and drop model. These allow you to drag multiple items and drag non-string data. For more information, see Dragging and Dropping Multiple Items.

For a list of common data types used for drag and drop, see Recommended Drag Types.

A quick reference is available for the best practice for dragging the following kinds of items:

See DataTransfer for a reference to the DataTransfer object.

Drag events

A number of events are used which are fired during various stages of the drag and drop operation. Note that only drag events are fired; mouse events such as mousemove are not fired during a drag operation. Also note that dragstart and dragend are not fired when dragging a file into the browser from the OS.

The dataTransfer property of all drag events holds data about the drag and drop operation.

dragstart
Fired on an element when a drag is started. The user is requesting to drag the element the dragstart event is fired at. During this event, a listener would set information such as the drag data and image to be associated with the drag. This event is not fired when dragging a file into the browser from the OS. For information about this, see Starting a Drag Operation.
dragenter
Fired when the mouse is first moved over an element while a drag is occurring. A listener for this event should indicate whether a drop is allowed over this location. If there are no listeners, or the listeners perform no operations, then a drop is not allowed by default. This is also the event to listen to if you want to provide feedback that a drop is allowed such as displaying a highlight or insertion marker. For information about this, see Specifying Drop Targets.
dragover
This event is fired as the mouse is moved over an element when a drag is occuring. Much of the time, the operation that occurs during a listener will be the same as the dragenter event. For information about this, see Specifying Drop Targets.
dragleave
This event is fired when the mouse leaves an element while a drag is occurring. Listeners should remove any highlighting or insertion markers used for drop feedback.
drag
This event is fired at the source of the drag, that is, the element where dragstart was fired, during the drag operation.
drop
The drop event is fired on the element where the drop occurred at the end of the drag operation. A listener would be responsible for retrieving the data being dragged and inserting it at the drop location. This event will only fire if a drop is desired. It will not fire if the user cancelled the drag operation, for example by pressing the Escape key, or if the mouse button was released while the mouse was not over a valid drop target. For information about this, see Performing a Drop.
dragend
The source of the drag will receive a dragend event when the drag operation is complete, whether it was successful or not. This event is not fired when dragging a file into the browser from the OS. See Finishing a Drag for more information.
{{HTML5ArticleTOC}}

Revision Source

<p>Firefox and other Mozilla applications support a number of features for handling drag and drop. This allows the user to click and hold the mouse button down over an element, drag it to another location, and release the mouse button to drop the element there. A translucent representation of what is being dragged will follow the mouse pointer during the drag operation. The drop location may be a different application. Web sites, extensions, and XUL applications may make use of this functionality to customize what elements may be dragged, the drag feedback, as well as specify where elements may be dropped.</p>
<div class="note">
  This section covers drag and drop in Firefox 3.5 (Gecko 1.9.1) and later. For the older API for Firefox 3.0 and earlier, which is not exposed to web pages, see the <a href="/en-US/docs/Drag_and_Drop" title="Older Drag and Drop API">older API documentation</a>.</div>
<h2 id="Drag_and_drop_basics">Drag and drop basics</h2>
<p>When a drag begins, a number of pieces of information may be provided:</p>
<ul>
  <li>the data to be dragged, which may be of a number of different formats. For example, textual data containing a string of text being dragged. For information about this, see <a href="/en-US/docs/DragDrop/Drag_Operations#Drag_Data" title="Drag Data">Drag Data</a>.</li>
  <li>the drag feedback image which appears beside the mouse pointer during the drag operation. This image may be customized; however, most of the time, you would not specify this, and a default image will be generated based on the element where the mouse was pressed down. To learn more about drag feedback images, see <a href="/en-US/docs/DragDrop/Drag_Operations#Setting_the_drag_feedback_image" title="Setting the Drag Feedback Image">Setting the Drag Feedback Image</a>.</li>
  <li>drag effects that are allowed. Three such effects are possible: <code>copy</code> to indicate that the data being dragged will be copied from its present location to the drop location, <code>move</code> to indicate that the data being dragged will be moved, and <code>link</code> to indicate that some form of relationship or connection will be created between the source and drop locations. During the drag operation, the drag effects may be modified to indicate that certain effects are allowed at certain locations. If allowed, a drop may occur at that location. See <a href="/en-US/docs/DragDrop/Drag_Operations#Drag_Effects" title="Drag Effects">Drag Effects</a> for more details.</li>
</ul>
<p>Mozilla and Firefox support a number of features not in the standard drag and drop model. These allow you to drag multiple items and drag non-string data. For more information, see <a href="/en-US/docs/DragDrop/Dragging_and_Dropping_Multiple_Items" title="Dragging and Dropping Multiple Items">Dragging and Dropping Multiple Items</a>.</p>
<p>For a list of common data types used for drag and drop, see <a href="/en-US/docs/DragDrop/Recommended_Drag_Types" title="Recommended Drag Types">Recommended Drag Types</a>.</p>
<p>A quick reference is available for the best practice for dragging the following kinds of items:</p>
<ul>
  <li><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#text" title="Text">Text</a></li>
  <li><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#link" title="Links">Links</a></li>
  <li><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#html" title="HTML and XML">HTML and XML</a></li>
  <li><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#file" title="Files">Files</a></li>
  <li><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#image" title="Images">Images</a></li>
  <li><a href="/en-US/docs/DragDrop/Recommended_Drag_Types#node" title="Document Nodes">Document Nodes</a></li>
</ul>
<p>See <a href="/en-US/docs/DragDrop/DataTransfer" title="DataTransfer">DataTransfer</a> for a reference to the DataTransfer object.</p>
<h2 id="events" name="events">Drag events</h2>
<p>A number of events are used which are fired during various stages of the drag and drop operation. Note that only drag events are fired; mouse events such as <code>mousemove</code> are not fired during a drag operation. Also note that <code>dragstart</code> and <code>dragend</code> are not fired when dragging a file into the browser from the OS.</p>
<p>The <a href="/en-US/docs/DragDrop/DataTransfer" title="dataTransfer">dataTransfer</a> property of all drag events holds data about the drag and drop operation.</p>
<dl>
  <dt>
    <code>dragstart</code></dt>
  <dd>
    Fired on an element when a drag is started. The user is requesting to drag the element the <code>dragstart</code> event is fired at. During this event, a listener would set information such as the drag data and image to be associated with the drag. This event is not fired when dragging a file into the browser from the OS. For information about this, see <a href="/en-US/docs/DragDrop/Drag_Operations#dragstart" title="Starting a Drag Operation">Starting a Drag Operation</a>.</dd>
  <dt>
    <code>dragenter</code></dt>
  <dd>
    Fired when the mouse is first moved over an element while a drag is occurring. A listener for this event should indicate whether a drop is allowed over this location. If there are no listeners, or the listeners perform no operations, then a drop is not allowed by default. This is also the event to listen to if you want to provide feedback that a drop is allowed such as displaying a highlight or insertion marker. For information about this, see <a href="/en-US/docs/DragDrop/Drag_Operations#droptargets" title="Specifying Drop Targets">Specifying Drop Targets</a>.</dd>
  <dt>
    <code>dragover</code></dt>
  <dd>
    This event is fired as the mouse is moved over an element when a drag is occuring. Much of the time, the operation that occurs during a listener will be the same as the dragenter event. For information about this, see <a href="/en-US/docs/DragDrop/Drag_Operations#droptargets" title="Specifying Drop Targets">Specifying Drop Targets</a>.</dd>
  <dt>
    <code>dragleave</code></dt>
  <dd>
    This event is fired when the mouse leaves an element while a drag is occurring. Listeners should remove any highlighting or insertion markers used for drop feedback.</dd>
  <dt>
    <code>drag</code></dt>
  <dd>
    This event is fired at the source of the drag, that is, the element where <code>dragstart</code> was fired, during the drag operation.</dd>
  <dt>
    <code>drop</code></dt>
  <dd>
    The <code>drop</code> event is fired on the element where the drop occurred at the end of the drag operation. A listener would be responsible for retrieving the data being dragged and inserting it at the drop location. This event will only fire if a drop is desired. It will not fire if the user cancelled the drag operation, for example by pressing the Escape key, or if the mouse button was released while the mouse was not over a valid drop target. For information about this, see <a href="/en-US/docs/DragDrop/Drag_Operations#drop" title="Performing a Drop">Performing a Drop</a>.</dd>
  <dt>
    <code>dragend</code></dt>
  <dd>
    The source of the drag will receive a dragend event when the drag operation is complete, whether it was successful or not. This event is not fired when dragging a file into the browser from the OS. See <a href="/en-US/docs/DragDrop/Drag_Operations#dragend" title="Finishing a Drag">Finishing a Drag</a> for more information.</dd>
</dl>
<div>
  {{HTML5ArticleTOC}}</div>
Revert to this revision