Jump to Table of Contents

Drag and Drop

The Drag and Drop Utility allows you to create a draggable interface efficiently, buffering you from browser-level abnormalities and enabling you to focus on the interesting logic surrounding your particular implementation. This component enables you to create a variety of standard draggable objects with just a few lines of code and then, using its extensive API, add your own specific implementation logic.

For more information about drag and drop as a design pattern, see the Yahoo! Design Pattern Library.

Getting Started

To include the source files for Drag and Drop and its dependencies, first load the YUI seed file if you haven't already loaded it.

<script src="http://yui.yahooapis.com/3.7.2/build/yui/yui-min.js"></script>

Next, create a new YUI instance for your application and populate it with the modules you need by specifying them as arguments to the YUI().use() method. YUI will automatically load any dependencies required by the modules you specify.

<script>
// Create a new YUI instance and populate it with the required modules.
YUI().use('dd', function (Y) {
    // Drag and Drop is available and ready for use. Add implementation
    // code here.
});
</script>

For more information on creating YUI instances and on the use() method, see the documentation for the YUI Global Object.

Using Drag and Drop

Basic Drag

You create a simple Drag instance by including the dd-drag module and using the following code:

YUI().use('dd-drag', function(Y) {
    var dd = new Y.DD.Drag({
        node: '#drag'
    });
});

Basic Proxy Drag

You create a simple Proxy Drag instance by including the dd-drag and dd-proxy modules and using the following code:

YUI().use('dd-drag', 'dd-proxy', function(Y) {
    var dd = new Y.DD.Drag({
        node: '#drag'
    }).plug(Y.Plugin.DDProxy); //This config option makes the node a Proxy Drag
});

Basic Drop Target

You create a simple Drop Target instance by including the dd-drop module and using the following code:

YUI().use('dd-drop', function(Y) {
    var drop = new Y.DD.Drop({
        node: '#drop'
    });
});

Using a Drag Handle

Drag handles allow you to specify what element will initiate a drag. For example, you may want the entire element to be able to be dragged, but you only want them to click on the header to do that (in case you have content that will not react well to a drag, like an input or an anchor).

<div id="demo">
    <h2>Drag Me Here</h2>
    <p>Can't drag me here</p>
</div>

Using the addHandle method on the Drag instance, you can tell the Drag to only be started if the user clicks on that element. Any selector string will work here.

var dd = new Y.DD.Drag({
    node: '#demo'
}).addHandle('h2');

You can also use the removeHandle method to remove a previously added handle.

Invalid Handles

The opposite of handles are Invalid Handles. This is a selector string that will never fire a drag event. By default the following HTML elements will not be draggable since adding the mouse events to them prohibit their actual use: textarea, input, a, button, select

If you need to drag one of these items, you will have to call removeInvalid on your Drag instance to remove it from the default list.

<ul>
    <li><a href="#"><img src="foo.png"></a></li>
</ul>

Now you create your Drag instance as usual, but call removeInvalid to allow the img to be dragged from inside the li.

var dd = new Y.DD.Drag({
    node: 'ul li'
}).removeInvalid('a');

Events

Drag and Drop for YUI 3 has been been packed with useful events to allow the implementer to control the end user experience.

* All Drag and Drop events bubble, by default, to the Drag and Drop Manager.

Event Target Preventable Stoppable Description
drag:mouseDown Drag yes yes Handles the mousedown/touchstart DOM event, checks to see if you have a valid handle then starts the drag timers.
drag:afterMouseDown Drag no no Fires after the mousedown/touchstart event has been cleared.
drag:mouseup Drag yes yes Fires the mouseup event.
drag:align Drag yes yes Fires when this node is aligned.
drag:removeHandle Drag no no Fires after a handle is removed.
drag:addHandle Drag no no Fires after a handle is added.
drag:removeInvalid Drag no no Fires after an invalid selector is removed.
drag:addInvalid Drag no no Fires after an invalid selector is added.
drag:start Drag no no Fires at the start of a drag operation.
drag:end Drag yes yes Fires at the end of a drag operation.
drag:drag Drag yes yes Fires every mousemove/touchmove during a drag operation.
drag:over Drag no no Fires when this node is over a Drop Target. (Fired from dd-drop)
drag:enter Drag no no Fires when this node enters a Drop Target. (Fired from dd-drop)
drag:exit Drag no no Fires when this node exits a Drop Target. (Fired from dd-drop)
drag:drophit Drag no no Fires when this node is dropped on a valid Drop Target. (Fired from dd-ddm-drop)
drag:dropmiss Drag no no Fires when this node is dropped on an invalid Drop Target. (Fired from dd-ddm-drop)
drop:over Drop no no Fires when a drag element is over this target.
drop:enter Drop no no Fires when a drag element enters this target.
drop:exit Drop no no Fires when a drag element exits this target.
drop:hit Drop no no Fires when a draggable node is dropped on this Drop Target. (Fired from dd-ddm-drop)

Event Bubbling

To allow for a truly Event driven application, all Drag and Drop related events are bubbled to the DragDropMgr.

This allows you to listen for all Drag and Drop events from a central location, per YUI instance.

This approach is also handy for situations where you are dynamically adding and removing items.

So instead of doing this:

var doSomething = function() {
    Y.log('Do Something Here');
};
dd1.on('drag:drag', doSomething);
dd2.on('drag:drag', doSomething);
dd3.on('drag:drag', doSomething);
dd4.on('drag:drag', doSomething);
dd5.on('drag:drag', doSomething);
dd6.on('drag:drag', doSomething);
dd7.on('drag:drag', doSomething);
dd8.on('drag:drag', doSomething);
dd9.on('drag:drag', doSomething);

You can now do this:

var doSomething = function() {
    Y.log('Do Something Here');
};
Y.DD.DDM.on('drag:drag', doSomething);

Delegate Dragging

Delegate dragging allows you to create a "list/group" of draggable items that are under a common "container". Using this approach, you can have hundreds of draggable items, yet only have one object created under the hood.

This approach is also handy for situations where you are dynamically adding and removing items from the "list" and need to make them draggable. Using Delegate you wouldn't have to create a new drag instance when adding or removing it.

YUI().use('dd-delegate', function(Y) {
    var del = new Y.DD.Delegate({
        container: '#demo', //The common container
        nodes: '.item' //The items to make draggable
    });
});

Note: DD.Delegate does not auto find your drop target items, if you change the nodes under the hood (add or remove) you need to call delegate.syncTargets(); to manage them.

CSS Class Names

The Drag and Drop Utility adds CSS class names for important moments in the drag and drop operation. Below you will find the list of these class names.

The Drag and Drop Utility doesn't ship with a default skin, so no style rules are attached to these class names. That is completely left up to the implementer.

Note: As of version 3.1.0, Drag and Drop changed it's classname prefix from yui-dd to yui3-dd to mimic the global change in skinning.

Class Name Target State
yui3-dd-draggable Drag Given to all Drag Nodes
yui3-dd-locked Drag Added when a Drag instance is locked
yui3-dd-dragging Drag Added while a Drag instance is active
yui3-dd-proxy Proxy Given to the Proxy Node
yui3-dd-drop Drop Given to all Drop Targets
yui3-dd-drop-locked Drop Added when a Drop instance is locked
yui3-dd-drop-active-valid Drop Added to a Drop when it is an valid target for the current drag operation
yui3-dd-drop-active-invalid Drop Added to a Drop when it is an invalid target for the current drag operation
yui3-dd-drop-over Drop Added when a Drag instance is over this Drop Target

Touch/Gesture Support

Native gesture support was added to DD in 3.2.0. This support is transparent and the implementor should not have to do anything to use this functionality. When dd is used, loader will check the device to see if it contains support for Gesture Events, if the device supports these events the dd-gestures module will automatically be loaded as well as it's dependencies. At this point, DD will operate as usual but it will utilize the native gesture events instead of mouse based events.

Module Descriptions

Drag and Drop for YUI 3 has been broken up into several modules to allow you, as the implementer, to pick how you want it to work and what code you need on your page.

Module Name Description
dd-drag Main drag class, this makes something draggable.
dd-proxy Adds proxy support to the main drag class.
dd-constrain Adds constrain support to the main drag class.
dd-scroll Adds node and window based scroll support.
dd-delegate Provides the ability to drag multiple nodes under a container element using only one Y.DD.Drag instance as a delegate.
dd-drop Drop Support, this is the support for all drop targets.
dd All of the Drag and Drop modules rolled up into one file.
Other Included Modules
dd-ddm-base Base DragDrop Manager, required to make something draggable.
dd-ddm Adds shim support, only needed when you need to drag over something that steals mouse events or you are targeting.
dd-ddm-drop Adds Drop support, only required when you have drop targets you need to interact with.

DD Plugins

In 3.2.0, some modules have been removed from the rollup and were converted to DD Plugins. Below are the list of plugins that are no longer in the dd rollup.

Plugin Description
dd-plugin Node plugin for Drag
dd-drop-plugin Node plugin for Drop
dd-gestures Node plugin for Gesture support. This module is automatically loaded by loader when dd is used on a device that supports gestures.

Known Issues

As of 3.6.0, window scrolling does not work properly on Safari 6 (build 8536.25) due to a regression in it's viewport reporting.