Methods
- Layout
- layout / .masonry()
- layoutItems
- stamp
- unstamp
- Adding & removing items
- appended
- prepended
- addItems
- remove
- Events
- on
- off
- once
- Utilities
- reloadItems
- destroy
- getItemElements
- jQuery.fn.data('masonry')
- Masonry.data
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');
});
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');
});
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')