Masonry - Cascading grid layout library

Install

A packaged source file includes everything you need to use Masonry.

• masonry.pkgd.min.js for production
• masonry.pkgd.js for development

Bower

If you are familiar with the command line and build processes, Masonry can be installed withBower. Masonry is built on dependencies. Bower takes care of these.

bower install masonry

Getting started

HTML

Masonry works on a container element with a group of similar child items.

<div id="container">
  <div class="item">...</div>
  <div class="item w2">...</div>
  <div class="item">...</div>
  ...
</div>

Include the Masonry script in your site.

<script src="/path/to/masonry.pkgd.min.js"></script>

CSS

All sizing of items is handled by your CSS.

.item { width: 25%; }
.item.w2 { width: 50%; }

Initialize with JavaScript

Initialize a Masonry instance with new Masonry( element, options ). The Masonry constructor accepts two arguments: the container element and an options object.

var container = document.querySelector('#container');
var msnry = new Masonry( container, {
  // options
  columnWidth: 200,
  itemSelector: '.item'
});

The element can be a selector string for a single element.

var msnry = new Masonry( '#container', {
  // options
});

Initialize in HTML

You can initialize Masonry in HTML, without writing any JavaScript. Add js-masonry to the class of the container element. Options can be set with a data-masonry-options attribute.

<div id="container" class="js-masonry"
  data-masonry-options='{ "columnWidth": 200, "itemSelector": ".item" }'>

Options set in HTML must be valid JSON. Keys need to be quoted, for example"itemSelector":. Note that the attribute value uses single quotes ', but the JSON entities use double-quotes ".

That’s it! Now let’s do some fun stuff with options and methods.

jQuery

jQuery is not required to use Masonry. But if you do enjoy jQuery, Masonry works with it as a jQuery plugin.

var $container = $('#container');
// initialize
$container.masonry({
  columnWidth: 200,
  itemSelector: '.item'
});

Get the Masonry instance with .data('masonry').

var msnry = $container.data('masonry');

Type: Object

Default: { position: 'relative' }

CSS styles that are applied to the container element. To disable Masonry from setting any CSS to the container element, set containerStyle: null.

The width of a column of a horizontal grid.

If columnWidth is not set, Masonry will use the outer width of the first element.

If set to an Element or Selector String, Masonry will use the width of that element. SeeElement sizing. Setting columnWidth with element sizing is recommended if you are using percentage widths.

Type: Object

Default: { opacity: 0, transform: 'scale(0.001)' }

Type: Boolean

Default: false

Enables layout on initialization. Set this to false to disable layout on initialization, so you can use methods or add events before the initial layout.

Type: Boolean

Default: true

Type: Boolean

Default: true

Type: Boolean

Default: true

Specifies which elements are stamped within the layout. These are special layout elements which will not be laid out by Masonry. Rather, Masonry will layout item elements belowstamped elements.

The stamp option stamps elements only when the Masonry instance is first initialized. You can stamp additional elements afterwards with the stamp method.

Type: String

Default: '0.4s'

Type: Object

Default: { opacity: 1, transform: 'scale(1)' }

msnry.addItems( elements )
// or with jQuery
$container.masonry( 'addItems', elements )

Unlike jQuery's on, Masonry's on only works with the specified events. msnry.on( 'click', function() {...}) will not work.

To listen for an event just once, return true in the event listener.