I love Mac apps, especially for their attention to detail. CoreAnimation makes it so easy to create useful and eye-pleasing effects, like the one in this video. Quicksand aims at providing a similar experience for users on the web.
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:
$('#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>Please note that data-* is a perfectly valid HTML5 attribute. If
you’re using older doctype, you can use a different attribute or even a custom function to
identify unique elements. See the examples for more.
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
});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:
| Name | Default | Description |
|---|---|---|
adjustHeight |
'auto' |
Adjusts the height of container to fit all the items, 'auto' for automatically adjusting before or after the animation (determined automatically), 'dynamic' for height adjustment animation, false for keeping the height constant. |
attribute |
'data-id' |
Attribute used to match items in collections. You can provide custom function to extract unique values (see the demos) |
duration |
750 |
How long the animation will take. In milliseconds. |
easing |
'swing' |
Easing for the animation. Use jQuery easing plugin for more easing options. |
enhancement |
function() {} |
If you wish to integrate their visual enhancements (eg. font replacement), specify a function that refreshes or re-applies enhancement to an item during the animation. |
useScaling |
true |
Use scaling (CSS3 transform) animation. Requires to include this plugin to your project. Turned off automatically if you did not. |
Version 1.2 features major performance tweaks out of the box. To improve performance, you can:
useScaling option to stop using CSS3 transforms in the animationadjustHeight: 'dynamic' in favor of false or 'auto'.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');
}
}
);
As it was stated earlier, Quicksand works by comparing two collections of items and replacing them. It’s that simple.
Advanced demonstrations include custom jQuery code to achieve some of the goals, like sorting or making Ajax calls. This code can be copied & used freely, but it’s not part of the plugin.
data-* attributes)I get an error TypeError: Result of expression ... easing ... [undefined] is not a function
. What happened?
You are using easing effect that's not built-in and forgot to include jQuery.easing plugin. You can download it from its home page. Alternatively, remove easing from your Quicksand options to stick with the default swing effect. It's not that bad!
I would like to filter my items in a different way. How can I do it?
There's only one thing that Quicksand can do and it's performing the animation. Quicksand does not filter and does not do any sorting. It's up to you to provide initial collection and destination collection. Yeah, a little custom programming is required.
How can I use Quicksand with radio buttons instead of links? I want to combine criteria when filtering my collection.
You need to learn how to use callbacks in jQuery to handle changes in forms. Next, you have to study jQuery selectors to filter items the way you like. Quicksand generates the animated transition between elements. It's up to you to filter and sort.
I'm a designer and I don't know how to start...
This plugin requires basic programming skills: using jQuery selectors and callbacks is a minimum knowledge required to implement it on your website. Copy-paste is cool but sorry dude, not this time. Good luck studying jQuery, it's not that hard!
easeInOutQuad)Tested under:
No Internet Explorer 6 support is planned. Ever.
Huge thanks go to Piotr Petrus for organizing the documentation, making demos and creating this stunning design.
Copyright © 2010 Jacek Galanciak, released under both MIT and GPL version 2 license.