Appendix

• Web fonts
• Typekit
• RequireJS
• Browserify
• Component libraries
• docReady
• classie
• eventie
• Animating item size
• Issues
• Reduced test cases
• Submitting issues
• Extra examples
• Upgrading from v2
• Additional resources

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 font events
• Google WebFont Loader: Events

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('.grid');
  msnry = new Masonry( container, {
    // options...
  });
});
// trigger masonry when fonts have loaded
Typekit.load({
  active: triggerMasonry,
  inactive: triggerMasonry
});

// or with jQuery
var $grid;

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

RequireJS

Masonry supports RequireJS.

You can require masonry.pkgd.js.

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

To use Masonry as a jQuery plugin with RequireJS and masonry.pkgd.js, you need to use jQuery Bridget.

// require the require function
requirejs( [ 'require', 'jquery', 'path/to/masonry.pkgd.js' ],
  function( require, $, Masonry ) {
    // require jquery-bridget, it's included in masonry.pkgd.js
    require( [ 'jquery-bridget/jquery.bridget' ],
    function() {
      // make Masonry a jQuery plugin
      $.bridget( 'masonry', Masonry );
      // now you can use $().masonry()
      $('.grid').masonry({...});
    }
  );
});

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( '.grid', {...});
});

You can require Bower dependencies and use Masonry as a jQuery plugin with jQuery Bridget.

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

requirejs( [
    'jquery',
    'masonry/masonry',
    'jquery-bridget/jquery.bridget'
  ],
  function( $, Masonry ) {
    // make Masonry a jQuery plugin
    $.bridget( 'masonry', Masonry );
    // now you can use $().masonry()
    $('.grid').masonry({...});
});

Browserify

Masonry works with Browserify. Install Masonry with npm.

npm install masonry-layout

var Masonry = require('masonry-layout');

var msnry = new Masonry( '.grid', {
  // options...
});

To use Masonry as a jQuery plugin with Browserify, you need to use jQuery Bridget

npm install jquery
npm install jquery-bridget

var $ = require('jquery');
var jQBridget = require('jquery-bridget');
var Masonry = require('masonry-layout');
// make Masonry a jQuery plugin
$.bridget( 'masonry', Masonry );
// now you can use $().masonry()
$('.grid').masonry({
  columnWidth: 80
});

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('.grid');
  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 );

Animating item size

You cannot transition or animate the size of an item element and properly lay out. But there is a trick — you can animate a child element of the item element.

<div class="grid">
  <!-- items have grid-item-content child elements -->
  <div class="grid-item">
    <div class="grid-item-content"></div>
  </div>
  ...

/* item is invisible, but used for layout
item-content is visible, and transitions size */
.grid-item,
.grid-item-content {
  width: 60px;
  height: 60px;
}
.grid-item-content {
  background: #09D;
  transition: width 0.4s, height 0.4s;
}

/* both item and item content change size */
.grid-item.is-expanded,
.grid-item.is-expanded .grid-item-content {
  width: 180px;
  height: 120px;
}

This technique works on items with responsive, percentage widths. Although, it does require a bit more JS. Check out the example on CodePen to see how it’s done.

.grid-item {
  width: 20%;
  height: 60px;
}

.grid-item-content {
  width:  100%;
  height: 100%;
  background: #09D;
  transition: width 0.4s, height 0.4s;
}
/* item has expanded size */
.grid-item.is-expanded {
  width: 60%;
  height: 120px;
}

Issues

Reduced test cases

Creating a reduced test case is the best way to debug problems and report issues. Read CSS Tricks on why they’re so great.

Create a reduced test case for Masonry by forking any one of the CodePen demos from these docs.

• A reduced test case clearly demonstrates the bug or issue.
• It contains the bare minimum HTML, CSS, and JavaScript required to demonstrate the bug.
• A link to your production site is not a reduced test case.

Creating a reduced test case is the best way to get your issue addressed. They help you point out the problem. They help us debug the problem. They help others understand the problem.

Submitting issues

Report issues on GitHub. Make sure to include a reduced test case. Without a reduced test case, your issue may be closed.

Extra examples

• Iteratively reveal items after each image is loaded. See explanation on issue #501
• Drag and drop in and out of Masonry (sort of)

Upgrading from v2

• smartresize jQuery plugin has been removed
• imagesLoaded no longer included, but is still recommended.
• jQuery animation has been removed. animationOptions has been removed. This means no animation for in IE8 and IE9.
• Corner stamp is now integrated as stamp option and stamp method
• isRTL option removed, use isOriginLeft: false instead
• isResizable option renamed to isResizeBound
• layout method renamed to layoutItems
• gutterWidth option renamed to gutter

Additional resources

• Masonry CodePens
• The Metafizzy blog has posts that cover specialized use cases
• My answers on Stack Overflow
• Sites using Masonry on Delicious
• Stack Overflow questions about Masonry
• Related Masonry links
• Other resources that are like Masonry but not