Mercutio is a layout plugin for jQuery. Think of it as the flip side of CSS floats. Whereas floating arranges elements horizontally then vertically, Mercutio arranges elements vertically then horizontally according to a grid. The result minimizes vertical gaps between elements of varying height, just like a mason fitting stones in a wall.

Minimum recommended configuration

Configuring Mercutio is fairly easy. Simply call the .mercutio() method on the container element. Depending on the layout, you’ll most likely need to specify one option.

For layouts with elements that span multiple widths, like the basic multi-column example:

$('#wrapper').mercutio({ columnWidth: 200 });

For layouts with elements that span the same width, like the basic single-column example:

$('#wrapper').mercutio({ singleMode: true });

No need to worry about how many columns, or width of gutters, or how big the container is. Thanks to the wonders of jQuery’s outerWidth() and innerWidth() methods, Mercutio appropriately accounts for the space of any margin, padding, and border-width set with CSS.

This plugin is designed to progressively enhance the layout, so ‘brick’ elements should be floated if JavaScript is disabled. Floating also ensures that the bricks width will be measured correctly.

Plugin options

$('#wrapper').mercutio({

  singleMode: false,
  // Disables measuring the width of each floated element.
  // Set to true if floated elements have the same width.
  // default: false

  columnWidth: 240,
  // Width in pixels of 1 column of your grid.
  // default: outer width of the first floated element.

  itemSelector: '.box:visible',
  // Additional selector to specify which elements inside
  // the wrapping element will be rearranged.
  // Required for Infinite Scroll with window resizing.

  resizeable: true,
  // Binds a Mercutio call to window resizes 
  // so layout appears fluid.
  // default: true

  animate: true,
  // Animates layout rearrangements.
  // default: false

  animationOptions: {},
  // A map of options for animation.

  appendedContent: $('.new_content'),
  // Additional container element for appended content.
  // Useful for Infinite Scroll integration.

  saveOptions: true,
  // Mercutio will use the options from previous Mercutio
  // calls by default, so you only have to enter in options once
  // default: true

},  function() {}
  // Optional callback.
  // 'this' will refer to the applicable elements Mercutio just rearranged

);

Code repository

This project lives on GitHub at github.com/desandro/mercutio, where you can follow progress, download all this documentation, grab the latest version of the script, or fork this project and make it better yourself.

There you can find an issue tracker where you can look through other people’s resolved issues or submit a new one for yourself. If you’re still having trouble, try looking over the FAQ.

Window resizing

By default, Mercutio binds a call to the browser window for resizing. But the rearrangement script is triggered only when the layout adds or loses a column, so you don’t have to worry about Mercutio slowing down window resizes, or with fixed layouts.

Handling images & other media

Since Mercutio measures the height of the elements when placing them, you will need to account for images and other media that haven’t loaded yet. For images, the best method is to specify the width and height of images inline.

<img src="img_file.jpg" width="280" height="160" />

If you’re using a PHP-based CMS, you can use the getimagesize function.

If this is not possible or if you’re dealing with @font-face fonts, another option is to call Mercutio after all media has loaded. This is done by calling the function inside of $(window).load() instead of $(document).ready().

$(window).load(function(){
  $('#wrapper').mercutio({ columnWidth: 200 });
});

Resolving anchor links

Since Mercutio relies on absolute positioning, any anchor links that occur within or after the wrapping element will not work when the page first loads. The following script is one solution.

$(window).load(function(){
  if ( window.location.hash ) {
    var destination = $( window.location.hash ).offset().top;
    $('html:not(:animated),body:not(:animated)').scrollTop( destination );
  }
});

This will set the window of the document to the appropriate place. These couple lines were taken from Cedric Dugas’s anchorAnything.

Examples in the wild

In addition to the examples below, see delicious links tagged with jquerymercutio and jQuery Mercutio Collection on Ember for screenshots.

• The Bygone Bureau
• Thought & Theory - Collection
• Scaffold Tumblr Theme by Mike Harding
• Pattern Tap
• PUMA Running | Media
• The Inspiration Stream | Veerle's blog 3.0
• thomas.matthews
• Rather Splendid
• Chromeography

Changelog

v1.3 3 Sep 2010

Revamped appendedContent to work with container elements. Plays nice with latest Infinite Scroll.

Revised layout for documentation to allow for more pages.

v1.2 12 Jun 2010

Support for filtering added

v1.1: 29 Apr 2010

Add animation

v1.0: 7 Dec 2009

Multi-column width support

Appending elements and Infinite Scroll support

Less obstrusive layout. No inserting additional markup.

Automatically binds event to window resizing

v0.4: 14 Jun 2009

Better fluid rearrangement support

v0.1: Feb 2009

Original release

Acknowledgments

• Paul Irish for his Infinite Scroll plugin, which served as a template I used to produce a plugin of my own. The appendedContent option was design to work specifically with Infinite Scroll. Infinite Scroll is packaged with these docs.
• Louis-Rémi Babé and Paul Irish for the jQuery SmartResize plugin. This adds a special smartresize event to jQuery, so window resize events do not have to be executed on every frame. This plugin is used within jQuery Mercutio.

License

jQuery Mercutio is licensed under the MIT license, just like jQuery itself. It may be used for personal and commercial applications.