Appendix

imagesLoaded

Unloaded images can throw off Masonry layouts and cause item elements to overlap. imagesLoaded resolves this issue. imagesLoaded works by triggering a callback after all child images have been loaded.

var container = document.querySelector('#container');
var msnry;
// initialize Masonry after all images have loaded
imagesLoaded( container, function() {
  msnry = new Masonry( container );
});
// or with jQuery
var $container = $('#container');
// initialize Masonry after all images have loaded  
$container.imagesLoaded( function() {
  $container.masonry();
});

Or initialize Masonry first, then trigger layout after images have loaded.

// initialize Masonry
var msnry = new Masonry( container );
// layout Masonry again after all images have loaded
imagesLoaded( container, function() {
  msnry.layout();
});
// or with jQuery
// initialize Masonry
var $container = $('#container').masonry();
// layout Masonry again after all images have loaded
$container.imagesLoaded( function() {
  $container.masonry();
});

Web fonts

Like images, unloaded web fonts can throw off Masonry. To resolve this, trigger layout after fonts have been loaded. Both Typekit and Google WebFont Loader provide font events to control scripts based on how fonts are loaded.

Typekit

Try the script below when using Masonry on a page with Typekit. This will trigger Masonry when the document is ready and again when fonts have loaded. Be sure to remove Typekit’s default script, try{Typekit.load();}catch(e){}.

var msnry;

function triggerMasonry() {
  // don't proceed if masonry has not been initialized
  if ( !msnry ) {
    return;
  }
  msnry.layout();
}
// initialize masonry on document ready
docReady( function() {
  var container = document.querySelector('#container');
  msnry = new Masonry( container, {
    // options...
  });
});
// trigger masonry when fonts have loaded
Typekit.load({
  active: triggerMasonry,
  inactive: triggerMasonry
});
// or with jQuery
var $container;

function triggerMasonry() {
  // don't proceed if $container has not been selected
  if ( !$container ) {
    return;
  }
  // init Masonry
  $container.masonry({
    // options...
  });
}
// trigger masonry on document ready
$(function(){
  $container = $('#container');
  triggerMasonry();
});
// trigger masonry when fonts have loaded
Typekit.load({
  active: triggerMasonry,
  inactive: triggerMasonry
});

Component libraries

Masonry includes several component libraries. You might have seen these used in the example code. You can use some of these libraries in your own code.

docReady

docReady triggers initialization logic when the document is ready, just like jQuery's $(document).ready(). docReady is used to initialize all the demos in these docs.

docReady( function() {
  // document is ready, let's do some fun stuff!
  var container = document.querySelector('#container');
  var msnry = new Masonry( container );
});

classie

classie has class helper functions. classie is not included with Masonry.

classie.has( element, 'my-class' ) // returns true/false
classie.add( element, 'my-new-class' ) // add new class
classie.remove( element, 'my-unwanted-class' ) // remove class
classie.toggle( element, 'my-class' ) // toggle class

eventie

Eventie makes event binding in IE8 legit.

var elem = document.querySelector('#my-elem');
function onElemClick( event ) {
  console.log( event.type + ' just happened on #' + event.target.id );
  // -> click just happened on #my-elem
}
// bind it
eventie.bind( elem, 'click', onElemClick );
// unbind it
eventie.unbind( elem, 'click', onElemClick );

Submitting issues

Reduced test case required

All bug reports and problem issues require a reduced test case. See CSS Tricks - Reduced Test Cases on why they "are the absolute, ... number one way to troubleshoot bugs."

I realize this guideline may seem a little harsh, but it dramatically helps both of you and me. Reduced test cases help you identify the issue at hand and understand your own code. On my side, they greatly reduce the amount of time spent resolving the issue.

Upgrading from v2

RequireJS

Masonry is compatible with RequireJS.

You can require masonry.pkgd.js.

requirejs( [
  'path/to/masonry.pkgd.js',
], function( Masonry ) {
  new Masonry('#container');
});

Or, you can manage dependencies with Bower. Set baseUrl to bower_components and set a path config for all your application code.

requirejs.config({
  baseUrl: 'bower_components/',
  paths: {
    app: '../'
  }
});

requirejs( [
  'masonry/masonry',
  'app/my-component.js'
], function( Masonry, myComp ) {
  new Masonry('#container');
});

RequireJS and jQuery

To use Masonry as a jQuery plugin with RequireJS, you’ll need to run jQuery bridget.

// if you are using masonry.pkgd.js,
// provide path to jquery.bridget as masonry.pkgd.js path
requirejs.config({
  paths: {
    'jquery-bridget/jquery.bridget': 'path/to/masonry.pkgd.js'
  }
});

requirejs( [
  'path/to/masonry.pkgd.js',
  'jquery-bridget/jquery.bridget'
], function( Masonry, bridget ) {
  // make Masonry a jQuery plugin
  bridget( 'masonry', Masonry );
  $('#container').masonry();
});

Extra examples

Additional resources