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).

var container = document.querySelector('#container');
var msnry = new Masonry( container );
container.appendChild( elem );
msnry.appended( elem );
msnry.layout();

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');
});

Click item to toggle size

Edit this demo or vanilla JS demo on CodePen

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.

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

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;
});

Edit this demo or vanilla JS demo on CodePen

unstamp

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

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

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

Adding & removing items

appended

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

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

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 );
});

Edit this demo or vanilla JS demo on CodePen

prepended

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

// jQuery
msnry.prepended( elements )
// vanilla JS
$grid.masonry( '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 );
});

Edit this demo or vanilla JS demo on CodePen

addItems

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

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

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');
});

Click items to remove

Edit this demo or vanilla JS demo on CodePen

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', 'arrangeComplete', function() {
  console.log('arrange 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;
});

Edit this demo or vanilla JS demo on CodePen

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.filteredItems.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 js-masonry" data-masonry-options='{...}'>...</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')