Getting Started

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

<script src="http://yui.yahooapis.com/3.18.1/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('sortable', function (Y) {
    // Sortable 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.

A Basic Sortable List

The most common use case of a sortable list is an Unordered List.

Below is the sample markup used to create a container and a list.

<div id="demo">
    <ul>
        <li>Item #1</li>
        <li>Item #2</li>
        <li>Item #3</li>
        <li>Item #4</li>
        <li>Item #5</li>
        <li>Item #6</li>
        <li>Item #7</li>
        <li>Item #8</li>
        <li>Item #9</li>
        <li>Item #10</li>
    </ul>
</div>

To turn this into a sortable list, you just need to create the Sortable object and tell it the container and the nodes.

The nodes can be any selector string that matches a child of the container. For performance reasons you will want to make the container an element that is as close to the nodes as possible. The farther away in the DOM the container is from the nodes the worse the performance will be.

YUI().use('sortable', function(Y) {
    var sortable = new Y.Sortable({
        container: '#demo',
        nodes: 'li',
        opacity: '.1'
    });
});

Note: Sortable does not auto find your drop target items, if you change the nodes under the hood (add or remove) you need to call sortable.sync() to manage them.

Events

Sortable uses DD.Delegate under the hood to handle the Drag and Drop operations. It sets itself as the bubbleTarget of the Delegate instance, so all DD-related events are bubbled to it.

For more information on DD related events, see the events section on the Drag and Drop page.

Joining Lists

By default, a Sortable list can only interact with itself; you can't drag from one Sortable list to another. But a Sortable instance can be configured to be joined with another Sortable instance.

There are four ways a Sortable list can be joined: inner, outer, full and none (none is the default).

YUI().use('sortable', function(Y) {
    var sortable1 = new Y.Sortable({
        container: '#demo1',
        nodes: 'li',
        opacity: '.1'
    });

    var sortable2 = new Y.Sortable({
        container: '#demo2',
        nodes: 'li',
        opacity: '.1'
    });

    sortable1.join(sortable2, 'full');
});

You can also join multiple lists in multiple ways to get the experience you are looking for.

YUI().use('sortable', function(Y) {
    var sortable1 = new Y.Sortable({
        container: '#demo1',
        nodes: 'li',
        opacity: '.1'
    });

    var sortable2 = new Y.Sortable({
        container: '#demo2',
        nodes: 'li',
        opacity: '.1'
    });

    var sortable3 = new Y.Sortable({
        container: '#demo3',
        nodes: 'li',
        opacity: '.1'
    });

    sortable1.join(sortable2, 'inner');
    sortable2.join(sortable3, 'outer');

    sortable3.join(sortable1, 'full');
    sortable3.join(sortable2, 'full');
});

Using DD Plugins

The DD.Delegate object bound to a Sortable instance is exposed to allow you to easily attach plugins to a Sortable instance.

The Sortable instance has a delegate namespace, which is a reference to the internal DD.Delegate instance.

var sortable = new Y.Sortable({
    container: '#demo',
    nodes: 'li'
});

sortable.delegate.dd.plug(SomeDDPlugin);