Quicksand

About

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.

Documentation

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:

1. Use plain HTML, like an unordered list.
2. Download data by an Ajax call
3. 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">iOS</li>
  <li data-id="android">Android</li>
  <li data-id="winmo">Windows Phone 7</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">iOS</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
});

CSS recommendations

1. When styling your items and their container, please use CSS class. Using ID may lead to strange results. Quicksand clones the container to simulate destination frame of the animation. Since it's impossible for two elements of the same ID to exist, styling your items/container via container ID should be avoided.
2. Quicksand needs to know the margin of body, container and collection items. If these elements have their margins, please use px (pixels), not ems. The plugin doesn't understand ems for now.

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 brought 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');
    }
  }
);

Examples

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.

1. Two different sets of HTML
2. Two sets of HTML with overlapping elements
3. Advanced: Sorting one set of HTML (cloning)
4. Advanced: Custom attribute function (getting rid of data-* attributes)
5. Advanced: Ajax call

So, go ahead and…

FAQ

1. Can I use use Quicksand in commercial projects?

   Yes! You can use it commercially without limitation, you can even use it in website templates you sell on ThemeForest.

2. 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!

3. 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. A little bit of custom programming is required.

4. 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.

5. 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, not this time. Good luck studying jQuery, it's not that hard!

Other crap

Requirements and dependencies

• Required: jQuery. Any version equal or greater than 1.6.1 should work. This includes jQuery 2.0+ and jQuery 3.0+.
• Optional: Use jQuery Easing for additional easing options (the best – easeInOutQuad)
• Optional: Use jquery.transform2d.js for additional CSS3 scaling animation; works fine without this plugin (utilizes fade efect instead)

Browser compatibility

The plugin should work in all browsers, including versions a few years behind. Internet Explorer 7 is the lowest supported version of IE.

Extra credits

Huge thanks go to Piotr Petrus for organizing the documentation, making demos and creating this stunning design.

Licensing

Copyright © 2010 Jacek Galanciak, released under both MIT and GPL version 2 license.