Masonry V4 · API

The Masonry is a library that powers grid-styled galleries in the J1 Template. It places images in evenly aligned columns and efficiently fills the vertical space, even when the images have different heights.

Masonry stacks images like bricks: it slots each image into the first place it fits, so the columns can have different heights but no big empty gaps. The result is a balanced layout that uses the available space well.

The Masonry API documentation pages are based on version 4.2.2 for the current J1 template version of 2026.x. The idea of providing this documentation is not to simply copy the original Masonry pages as duplicates. For better readability and usability, all pages are restructured and enhanced by code examples or improved description texts.

Overview

Masonry is a small JavaScript library that arranges items in a grid. It does not use fixed rows. Instead, it places each item into the shortest open column, the way a bricklayer fills the gaps in a wall. The result is a tidy grid with no large empty gaps, even when the items have different heights.

Masonry Gallery

The Masonry API is the set of options, methods and events you use from JavaScript to build and control a grid. In the J1 Template you normally do not call this API yourself. Instead, you write a few YAML settings and the J1 Masonry adapter turns them into the correct JavaScript for every grid on the page. Reading this manual is still useful, because the Masonry options you set in YAML use the same names as the API options described on the following pages.

In J1, a grid is configured with three YAML files. They are merged together in the order shown below, and later files override earlier ones:

_data/modules/defaults/masonry.yml: The built-in default settings that apply to every grid.
_data/modules/masonry_control.yml: Your own settings, one entry per grid (the grid id, its type, the responsive columns, gutters, captions, lightbox, and so on).
_data/modules/masonry_media.yml: The content of each grid (the list of images or videos). Content is matched to a grid by its id.

Every grid has a type that decides what it shows:

image: A grid of images, optionally opened in a lightbox when clicked.
video: A grid of videos (YouTube or self-hosted HTML5), played with lightGallery.
post: A grid built automatically from the blog posts of a chosen group.
collection: A grid built automatically from the documents of a Jekyll collection.

Features

The Masonry module for J1 provides the following key features:

Name	Description
`Cascading grid`	Each item is placed into the shortest column, filling vertical gaps for a balanced, brick-like layout.
`Responsive columns`	The number of columns adapts to the screen size using the Bootstrap breakpoints `xs`, `sm`, `md`, `lg` and `xl`.
`Captions`	Optional caption text placed below, above or centered on each item. A caption can be revealed when the item is hovered.
`Image filters`	Optional CSS filters such as `grayscale`, `contrast` and `brightness` applied to the images.
`Lightbox`	Optional lightbox on image and video grids, using PhotoSwipe (`ps`), lightGallery (`lg`) or Lightbox2 (`lb`).
`Content types`	A grid can be filled from images, videos, blog posts or a Jekyll collection.

Initialization

When the grid’s HTML is on the page, Masonry is started like so. Because an image has no known height until it has loaded, run the layout method again after each image loads:

// init Masonry
var $grid = $('.grid').masonry({
  // options...
});
// layout Masonry after each image loads
$grid.imagesLoaded().progress( function() {
  $grid.masonry('layout');
});

Or, initialise Masonry only after all images have loaded:

var $grid = $('.grid').imagesLoaded( function() {
  // init Masonry after all images have loaded
  $grid.masonry({
    // options...
  });
});

Initialisation in J1 Template

In a J1 site you do not write the call above yourself. The J1 Masonry adapter builds it for you from your YAML configuration.

The adapter:

waits until the page is loaded and the grid’s HTML has been fetched and inserted into the page. The HTML is loaded on demand by AJAX from a generated data file (see the xhr_data_path setting),
waits a short, configurable moment (initTimeout, 1200 ms by default) so the browser can finish rendering the freshly inserted HTML,
reads the settings for each grid from the merged YAML configuration,
starts Masonry for every grid whose enabled key is true,
optionally attaches a lightbox on top of the grid when lightbox.enabled is true. The kind of lightbox (PhotoSwipe, lightGallery or Lightbox2) is chosen by lightbox.type.

You can still reach a running grid from JavaScript. Get the Masonry instance with jQuery, using $('<your_grid_id>').data('masonry'), or with Masonry.data(document.querySelector('<your_grid_id>')). You can then call any of Methods listed further down.

HTML Layout

Masonry works on a container element that holds a number of item elements. You give the container a class (for example .grid) and give each item a class (for example .grid-item). Masonry then measures the items and arranges them into columns. All sizing and spacing of the items is done with your own CSS; Masonry only takes care of the positioning.

In the J1 Template you normally do not write this markup by hand. The grid HTML is generated for you from your YAML settings and uses Bootstrap rows and columns (.row, .col-*, .card) instead of the plain .grid / .grid-item classes shown below. The examples on this page describe the underlying Masonry library, which is helpful for understanding how the options work.

Item sizing

All sizing and styling of items is handled by your own CSS.

<div class="grid">
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  <div class="grid-item grid-item--height2"></div>
  ...
</div>

.grid-item {
  float: left;
  width: 80px;
  height: 60px;
  border: 2px solid hsla(0, 0%, 0%, 0.5);
}
.grid-item--width2 { width: 160px; }
.grid-item--height2 { height: 140px; }

Responsive layouts

Item sizes can be set with percentages for responsive layouts. With the masonry layout mode, set percentage-width columnWidth with Element sizing (see next section below). Set percentPosition to true so item positions are likewise set with percentages to reduce adjustment transitions on window resize.

<div class="grid">
  <!-- width of .grid-sizer used for columnWidth -->
  <div class="grid-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
/* 2 columns */
.grid-item--width2 { width: 40%; }

$('.grid').masonry({
  // set itemSelector so .grid-sizer is not used in layout
  itemSelector: '.grid-item',
  // use element for option
  columnWidth: '.grid-sizer',
  percentPosition: true
})

Element sizing

Sizing options columnWidth and gutter can be set with an element. The size of the element is then used as the value of the option.

<div class="grid">
  <!-- .grid-sizer empty element, only used for element sizing -->
  <div class="grid-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
/* 2 columns wide */
.grid-item--width2 { width: 40%; }

// use outer width of grid-sizer for columnWidth
columnWidth: '.grid-sizer',
// do not use .grid-sizer in layout
itemSelector: '.grid-item',
percentPosition: true

The option can be set to a Selector String or an Element.

// set to a selector string
// first matching element within container element will be used
columnWidth: '.grid-sizer'
// set to an element
columnWidth: $grid.find('.grid-sizer')[0]

Element sizing options allow you to control the sizing of the Masonry layout within your CSS. This is useful for responsive layouts and media queries.

/* 3 columns by default */
.grid-sizer { width: 33.333%; }
@media screen and (min-width: 768px) {
  /* 5 columns for larger screens */
  .grid-sizer { width: 20%; }
}

Options

All options are optional, but columnWidth and itemSelector are recommended.

// jQuery
$('.grid').masonry({
  columnWidth: 200,
  itemSelector: '.grid-item'
});

// vanilla JS
var msnry = new Masonry( '.grid', {
  columnWidth: 200,
  itemSelector: '.grid-item'
});

<!-- in HTML -->
<div class="grid" data-masonry='{ "columnWidth": 200, "itemSelector": ".grid-item" }'>

In the J1 Template you set these options in YAML, not in JavaScript. The names are the same. For example, transitionDuration in YAML becomes the transitionDuration option shown here. J1 ships sensible defaults in _data/modules/defaults/masonry.yml, and you can override them per grid in _data/modules/masonry_control.yml.

itemSelector

Specifies which child elements will be used as item elements in the layout. It is recommend always setting itemSelector.

The option itemSelector is useful to exclude sizing elements or other elements that are not part of the layout.

itemSelector: '.grid-item'

<div class="grid">
  <!-- do not use banner in Masonry layout -->
  <div class="static-banner">Static banner</div>
  <div class="grid-item"></div>
  <div class="grid-item"></div>
  ...
</div>

columnWidth

Aligns items to a horizontal grid.

Recommend to set columnWidth. If columnWidth is not set, Masonry will use the outer width of the first item.

columnWidth: 80

Use Element sizing for responsive layouts with percentage widths. Set columnWidth to an Element or Selector String to use the outer width of the element for the size of the column.

<div class="grid">
  <!-- .grid-sizer empty element, only used for element sizing -->
  <div class="grid-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }
/* 2 columns wide */
.grid-item--width2 { width: 40%; }

// use outer width of grid-sizer for columnWidth
columnWidth: '.grid-sizer',
itemSelector: '.grid-item',
percentPosition: true

gutter

Adds horizontal space between item elements.

gutter: 10

.grid-item {
  margin-bottom: 10px;
}

To set vertical space between elements, use margin CSS.

Use Element sizing for responsive layouts with percentage widths. Set gutter to an Element or Selector String to use the outer width of the element.

<div class="grid">
  <div class="grid-sizer"></div>
  <div class="gutter-sizer"></div>
  <div class="grid-item"></div>
  <div class="grid-item grid-item--width2"></div>
  ...
</div>

.grid-sizer,
.grid-item { width: 22%; }
.gutter-sizer { width: 4%; }
.grid-item--width2 { width: 48%; }

columnWidth: '.grid-sizer',
gutter: '.gutter-sizer',
itemSelector: '.grid-item',
percentPosition: true

horizontalOrder

Lays out items to (mostly) maintain horizontal left-to-right order.

horizontalOrder: true

// default, items have no horizontal order
// horizontalOrder: false

percentPosition

Sets item positions in percent values, rather than pixel values. percentPosition: ``true works well with percent-width items, as items will not transition their position on resize.

// set positions with percent values
percentPosition: true,
columnWidth: '.grid-sizer',
itemSelector: '.grid-item'

/* fluid 5 columns */
.grid-sizer,
.grid-item { width: 20%; }

stamp

Specifies which elements are stamped within the layout. Masonry will layout items below stamped elements.

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

<div class="grid">
  <div class="stamp stamp1"></div>
  <div class="stamp stamp2"></div>
  <div class="grid-item"></div>
  <div class="grid-item"></div>
  ....
</div>

// specify itemSelector so stamps do get laid out
itemSelector: '.grid-item',
// stamp elements
stamp: '.stamp'

/* position stamp elements with CSS */
.stamp {
  position: absolute;
  background: orange;
  border: 4px dotted black;
}
.stamp1 {
  left: 30%;
  top: 10px;
  width: 20%;
  height: 100px;
}
.stamp2 {
  right: 10%;
  top: 20px;
  width: 70%;
  height: 30px;
}

fitWidth

Sets the width of the container to fit the available number of columns, based the size of container’s parent element. When enabled, you can center the container with CSS.

fitWidth was previously isFitWidth in Masonry v3. isFitWidth will still work in Masonry v4.

fitWidth: `true does not work with Element sizing with percentage width. Either columnWidth needs to be set to a fixed size, like columnWidth: 120, or items need to have a fixed size in pixels, like width: 120px. Otherwise, the container and item widths will collapse on one another.

fitWidth: true

/* center container with CSS */
.grid {
  margin: 0 auto;
}

originLeft

Controls the horizontal flow of the layout. By default, item elements start positioning at the left, with originLeft: true. Set originLeft: ``false for right-to-left layouts.

Option originLeft was previously isOriginLeft in Masonry v3. isOriginLeft still work in Masonry v4.

originLeft: false

originTop

Controls the vertical flow of the layout. By default, item elements start positioning at the top, with originTop: true. Set originTop: ``false for bottom-up layouts. It’s like Tetris!

Option`originTop` was previously isOriginTop in Masonry v3. isOriginTop still work in Masonry v4.

originTop: false

containerStyle

CSS styles that are applied to the container element.

// default
// containerStyle: { position: 'relative' }
// disable any styles being set on container
// useful if using absolute position on container
containerStyle: null

transitionDuration

Duration of the transition when items change position or appearance, set in a CSS time format. Default: transitionDuration: '0.4s'

// fast transitions
transitionDuration: '0.2s'
// slow transitions
transitionDuration: '0.8s'
// no transitions
transitionDuration: 0

stagger

Staggers item transitions, so items transition incrementally after one another. Set as a CSS time format, '0.03s', or as a number in milliseconds, 30.

stagger: 30

Click item to toggle size

resize

Adjusts sizes and positions when window is resized. Enabled by default resize: true.

Option resize was previously isResizeBound in Masonry v3. isResizeBound still work in Masonry v4.

// disable window resize behavior
resize: false

/* grid has fixed width */
.grid {
  width: 320px;
}

initLayout

Enables layout on initialization. Enabled by default.

Set initLayout to `false to disable layout on initialization, so you can use Masonry Methods or add Masonry events before the initial layout.

var $grid = $('.grid').masonry({
  // disable initial layout
  initLayout: false,
  //...
});
// bind event
$grid.masonry( 'on', 'layoutComplete', function() {
  console.log('layout is complete');
});
// trigger initial layout
$grid.masonry();

initLayout was previously isInitLayout in Masonry v3. Deprecated isInitLayout still work in Masonry v4.

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

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

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 — type Array of Masonry.Items
isStill — type Boolean (Disable 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 — type 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.

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

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

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

// 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 — type 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.

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

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

addItems does not lay out new items like appended or prepended does (see above).

remove

Removes elements from the Masonry instance and DOM.

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

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

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 — type 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 — type Element or Selector String
msnry — type 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')

Event binding

Masonry can tell you when things happen, for example when a layout has finished or when items have been removed. You react to these events by registering a function that Masonry calls at the right moment. Events can be bound with jQuery or with plain (vanilla) JavaScript, as shown below.

jQuery event binding

Bind events with jQuery with standard jQuery event methods .on(), .off(), and .one().

// jQuery
var $grid = $('.grid').masonry({...});
function onLayout() {
  console.log('layout done');
}
// bind event listener
$grid.on( 'layoutComplete', onLayout );
// un-bind event listener
$grid.off( 'layoutComplete', onLayout );
// bind event listener to be triggered just once. note ONE not ON
$grid.one( 'layoutComplete', function() {
  console.log('layout done, just this one time');
});

jQuery event listeners have an event argument, whereas vanilla JS listeners do not.

// jQuery, has event argument
$grid.on( 'layoutComplete', function( event, items ) {
  console.log( items.length );
});
// vanilla JS, no event argument
msnry.on( 'layoutComplete', function( items ) {
  console.log( items.length );
});

Vanilla JS event binding

Bind events with vanilla JS with on(), .off(), and .once() methods.

// vanilla JS
var msnry = new Masonry( '.grid', {...});
function onLayout() {
  console.log('layout done');
}
// bind event listener
msnry.on( 'layoutComplete', onLayout );
// un-bind event listener
msnry.off( 'layoutComplete', onLayout );
// bind event listener to be triggered just once
msnry.once( 'layoutComplete', function() {
  console.log('layout done, just this one time');
});

Masonry events

Every Masonry instance offers three methods to manage event listeners: on to add a listener, off to remove one, and once to add a listener that runs only a single time. The event names you can listen for are layoutComplete and removeComplete, both described further below.

on

Adds a Masonry event listener.

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

eventName — type String (Name of a Masonry event)
listener — type Function

off

Removes a Masonry event listener.

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

eventName — type String (Name of the Masonry event)
listener — type 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 — type String (Name of a Masonry event)
listener — type Function

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

layoutComplete

Triggered after a layout and all positioning transitions have completed.

// jQuery
$grid.on( 'layoutComplete', function( event, laidOutItems ) {...} )
// vanilla JS
msnry.on( 'layoutComplete', function( laidOutItems ) {...} )

laidOutItems — items that were laid out

$grid.on( 'layoutComplete',
  function( event, laidOutItems ) {
    console.log( 'Masonry layout completed on ' +
      laidOutItems.length + ' items' );
  }
);

removeComplete

Triggered after an item element has been removed.

// jQuery
$grid.on( 'removeComplete', function( event, removedItems ) {...} )
// vanilla JS
msnry.on( 'removeComplete', function( removedItems ) {...} )

removedItems — Array of items that were removed.

$grid.on( 'removeComplete',
  function( event, removedItems ) {
    notify( 'Removed ' + removedItems.length + ' items' );
  }
);