#

Jump to Table of Contents

# Sortable

The Sortable Utility allows you to create a sortable list from a container and a group of children. It also allows you to join lists together in various ways.

## 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.10.3/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).

Join Type | Description
--- | ---
`inner` | Items in the joined list can be moved into the main list but items in the main list can not be moved to the joined list.
`outer` | Items in the main list can be moved into the joined list but items in the joined list can not be moved to the main list.
`full` | All items in both lists can be moved into and out of any other joined list.
`none` | The default join type. No interaction with other lists.

    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);