How it works

At the very basic level, Quicksand replaces one collection of items with another. All you need to do is provide those two sets of items. You can do it in a couple of ways:

• Use plain HTML, like an unordered list.
• Download data by an Ajax call
• Transform HTML items by JavaScript (for example, sort them differently)

Calling

$('#source').quicksand( $('#destination li') );

This will work for the following HTML:

<ul id="source">
 <li data-id="iphone">iPhone OS</li>
 <li data-id="android">Android</li>
 <li data-id="winmo">Windows Mobile</li>
</ul>

<ul id="destination" class="hidden">
 <li data-id="macosx">Mac OS X</li>
 <li data-id="macos9">Mac OS 9</li>
 <li data-id="iphone">iPhone OS</li>
</ul>

First container (source) is visible to the user. Second container (destination) is provided as the first argument of Quicksand.

You need data-id attributes so that the plugin can identify the same elements within source and destination collections. If elements exists in both collections (the same data-id), it’s the same to Quicksand.

If you want to include a callback function, add it as a last argument:

$('#source').quicksand( $('#destination li'), function() {
 // callback code
});

Parameters

You can modify Quicksand by using optional parameters argument.

$('#source').quicksand( $('#destination li'), {
 name: value
});

Or

$('#source').quicksand( $('#destination li'), {
 name: value
}, function() {
 // callback code
});

List of available params:

Performance

Version 1.2 features major performance tweaks out of the box. To improve performance, you can:

1. turn off useScaling option to stop using CSS3 transforms in the animation
2. stop using adjustHeight: 'dynamic' in favor of false or 'auto'.

Integration with other plugins

When your items have functional enhancements (eg. tooltips), remember to use callback to apply them on newly cloned objects:

$("#content").quicksand($("#data > li"), 
  {
    duration: 1000,
  }, function() { // callback function
    $('#content a').tooltip();
  }
);

When your items are visually enhanced (eg. font replacement), use enhancement function to refresh/apply the effect during the animation:

$("#content").quicksand($("#data > li"), 
  {
    duration: 1000,
    enhancement: function() {
      Cufon.refresh('#content span');
    }
  }
);