Methods

Methods are actions done by Masonry instances.

With jQuery, methods follow the jQuery UI pattern .masonry( 'methodName' /* arguments */ ).

$grid.masonry()
  .append( elem )
  .masonry( 'appended', elem )
  // layout
  .masonry();

jQuery chaining is broken by methods that return values: (i.e. getItemElements, getItem, on, and off).

Vanilla JavaScript methods look like masonry.methodName( /* arguments */ ). Unlike jQuery methods, they cannot be chained together.

// vanilla JS
var msnry = new Masonry( '.grid', {...});
gridElement.appendChild( elem );
msnry.appended( elem );
msnry.layout();

Layout

layout / .masonry()

Lays out all item elements. layout is useful when an item has changed size, and all items need to be laid out again.

// jQuery
$grid.masonry()
// vanilla JS
msnry.layout()

var $grid = $('.grid').masonry({
  columnWidth: 80
});
// change size of item by toggling gigante class
$grid.on( 'click', '.grid-item', function() {
  $(this).toggleClass('gigante');
  // trigger layout after item size changes
  $grid.masonry('layout');
});

layoutItems

Lays out specified items.

// jQuery
$grid.masonry( 'layoutItems', items, isStill )
// vanilla JS
msnry.layoutItems( items, isStill )

items Array of Masonry.Items

isStill Boolean Disables transitions

stamp

Stamps elements in the layout. Masonry will lay out item elements around stamped elements.

// jQuery
$grid.masonry( 'stamp', elements )
// vanilla JS
msnry.stamp( elements )

elements Element, jQuery Object, NodeList, or Array of Elements

Set itemSelector so that stamps do not get used as layout items.

var $grid = $('.grid').masonry({
  // specify itemSelector so stamps do get laid out
  itemSelector: '.grid-item',
  columnWidth: 80
});
var $stamp = $grid.find('.stamp');
var isStamped = false;

$('.stamp-button').on( 'click', function() {
  // stamp or unstamp element
  if ( isStamped ) {
    $grid.masonry( 'unstamp', $stamp );
  } else {
    $grid.masonry( 'stamp', $stamp );
  }
  // trigger layout
  $grid.masonry('layout');
  // set flag
  isStamped = !isStamped;
});

unstamp

Un-stamps elements in the layout, so that Masonry will no longer layout item elements around them. See demo above.

// jQuery
$grid.masonry( 'unstamp', elements )
// vanilla JS
msnry.unstamp( elements )

elements Element, jQuery Object, NodeList, or Array of Elements

Adding & removing items

appended

Adds and lays out newly appended item elements to the end of the layout.

// jQuery
$grid.masonry( 'appended', elements )
// vanilla JS
msnry.appended( elements )

elements Element, jQuery Object, NodeList, or Array of Elements

$('.append-button').on( 'click', function() {
  // create new item elements
  var $items = $('<div class="grid-item">...</div>');
  // append items to grid
  $grid.append( $items )
    // add and lay out newly appended items
    .masonry( 'appended', $items );
});

While jQuery can add an HTML string with .append(), Masonry's appended cannot. When adding content with jQuery ajax methods like $.get() or $.ajax(), wrap HTML content string in a jQuery object to use it with appended.

// does not work
$.get( 'page2', function( content ) {
  // HTML string added, but items not added to Masonry
  $grid.append( content ).masonry( 'appended', content );
});

// does work
$.get( 'page2', function( content ) {
  // wrap content in jQuery object
  var $content = $( content );
  // add jQuery object
  $grid.append( $content ).masonry( 'appended', $content );
});

prepended

Adds and lays out newly prepended item elements at the beginning of layout.

// jQuery
$grid.masonry( 'prepended', elements )
// vanilla JS
msnry.prepended( elements )

elements Element, jQuery Object, NodeList, or Array of Elements

$('.prepend-button').on( 'click', function() {
  // create new item elements
  var $items = $('<div class="grid-item">...</div>');
  // prepend items to grid
  $grid.prepend( $items )
    // add and lay out newly prepended items
    .masonry( 'prepended', $items );
});

addItems

Adds item elements to the Masonry instance. addItems does not lay out items like appended or prepended.

// jQuery
$grid.masonry( 'addItems', elements )
// vanilla JS
msnry.addItems( elements )

elements Element, jQuery Object, NodeList, or Array of Elements

remove

// jQuery
$grid.masonry( 'remove', elements )
// vanilla JS
msnry.remove( elements )

Removes elements from the Masonry instance and DOM.

elements Element, jQuery Object, NodeList, or Array of Elements

$grid.on( 'click', '.grid-item', function() {
  // remove clicked element
  $grid.masonry( 'remove', this )
    // layout remaining item elements
    .masonry('layout');
})

Events

on

Adds a Masonry event listener.

// jQuery
var msnry = $grid.masonry( 'on', eventName, listener )
// vanilla JS
msnry.on( eventName, listener )

eventName String Name of a Masonry event

listener Function

off

Removes a Masonry event listener.

// jQuery
var msnry = $grid.masonry( 'off', eventName, listener )
// vanilla JS
msnry.off( eventName, listener )

eventName String Name of a Masonry event

listener Function

once

Adds a Masonry event listener to be triggered just once.

// jQuery
var msnry = $grid.masonry( 'once', eventName, listener )
// vanilla JS
msnry.once( eventName, listener )

eventName String Name of a Masonry event

listener Function

$grid.masonry( 'once', 'layoutComplete', function() {
  console.log('layout is complete, just once');
})

Utilities

reloadItems

Recollects all item elements.

For frameworks like Angular and React, reloadItems may be useful to apply changes to the DOM to Masonry.

// jQuery
$grid.masonry('reloadItems')
// vanilla JS
msnry.reloadItems()

destroy

Removes the Masonry functionality completely. destroy will return the element back to its pre-initialized state.

// jQuery
$grid.masonry('destroy')
// vanilla JS
msnry.destroy()

var masonryOptions = {
  itemSelector: '.grid-item',
  columnWidth: 80
};
// initialize Masonry
var $grid = $('.grid').masonry( masonryOptions );
var isActive = true;

$('.toggle-button').on( 'click', function() {
  if ( isActive ) {
    $grid.masonry('destroy'); // destroy
  } else {
    $grid.masonry( masonryOptions ); // re-initialize
  }
  // set flag
  isActive = !isActive;
});

getItemElements

Returns an array of item elements.

// jQuery
var elems = $grid.masonry('getItemElements')
// vanilla JS
var elems = msnry.getItemElements()

elems Array of Elements

jQuery.fn.data('masonry')

Get the Masonry instance from a jQuery object. Masonry instances are useful to access Masonry properties.

var msnry = $('.grid').data('masonry')
// access Masonry properties
console.log( msnry.items.length + ' filtered items'  )

Masonry.data

Get the Masonry instance via its element. Masonry.data() is useful for getting the Masonry instance in JavaScript, after it has been initalized in HTML.

var msnry = Masonry.data( element )

element Element or Selector String

msnry Masonry

<!-- init Masonry in HTML -->
<div class="grid" data-masonry='{...}'>...</div>

// jQuery
// pass in the element, $element[0], not the jQuery object
var msnry = Masonry.data( $('.grid')[0] )

// vanilla JS
// using an element
var grid = document.querySelector('.grid')
var msnry = Masonry.data( grid )
// using a selector string
var msnry = Masonry.data('.grid')