Dan Birlew

Las Vegas Web Developer, Designer, Programmer, and Author

Updated Masonry in WordPress

Posted June 25th, 2014 at 10:40am by Dan Birlew in Blog, jQuery. 2 Comments on Updated Masonry in WordPress

Masonry by David DeSandro is a JavaScript library that automatically sorts and places elements in nicely spaced columns, and even allows for elements that span multiple columns. You’ve seen similar scripts run on Pinterest and other places. The script rearranges elements on screen resize, making Masonry quite handy in building responsive layouts.

I’ve not only presented publicly regarding how to use Masonry in WordPress, I’ve provided several tutorials. Click the “Articles in this Series” links in the sidebar to read more.

As of WordPress version 3.9, the version of Masonry included in WordPress has been updated. The most recent version is 3, whereas the previous version was only Masonry 1.7, so this is quite a leap forward.

The newer version of Masonry is far easier to use in WordPress. No longer dependent on jQuery, all that’s required to use Masonry in plugins and themes is to enqueue the script (using the script handle ‘masonry’ instead of ‘jquery-masonry’) and then declare your default Masonry values within your HTML… That’s right! No more setting up a jQuery function to activate Masonry!

Enqueue the script as normal by adding the following snippet to your plugin or theme’s functions.php file:

function my_masonry(){
add_action('wp_enqueue_scripts', 'my_masonry');

Replace “my_masonry” with your own function name if needed, or simply add the script call to another function that enqueues all your scripts. Check your source code to make sure that Masonry is enqueued. If not, make sure your theme includes wp_footer before the closing body tag of your html.

With Masonry enqueued, simply navigate in your code to the element that contains all of the items you want Masonry to control and arrange, such as:

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

Add the class “js-masonry” to the container element, and set essential options such as “columnWidth” and “itemSelector” using valid JSON markup in the custom data-masonry-options attribute, such as:

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

Masonry will now arrange in columns all of the elements with class “item” that are children of “container”. If all your “item” elements are 200px wide in your stylesheet, then you’re done.

By setting additional classes to elements you can make them span 2 or more columns, also using CSS. If the html you are arranging with Masonry is generated by WordPress, such as in The Loop, then the easiest way to inject additional classes into your elements is with additional post formats. Whether you set things as “gallery” or “aside” or “image” is irrelevant, it’s what you do with these post formats in your CSS that counts as far as Masonry is concerned:

.item .format-image{
.item .format-aside{

In the example above, Masonry will layout all elements with class “item” in 200 px columns. Items with the additional class .format-image (inserted by saving the post as an Image in the post editor) will span two columns, and items with the class .format-aside will span three. The other items will rearrange around these wider elements… which may in some instances cause items to be arranged non-chronologically. However, this is a mild caveat that is harder to fight than it may be worth, for a temporary situation.

The ImagesLoaded plugin (also by DeSandro) is no longer included in Masonry, so if you are using images or thumbnails in your Masonry-enabled layout and having issues with element spacing and margins, it’s because Masonry is calculating the height and width of elements prior to the images being loaded, which throws off the math. ImagesLoaded is not included in WordPress separated, so you’ll need to download the file, add it to your code files and enqueue them using relative path, such as:

wp_enqueue_script( 'imagesLoaded',
 get_stylesheet_directory_uri() . '/js/imagesLoaded.js', array( 'jquery' ) );

This extra line of code can be added to your plugin or theme functions.php file, even using the same function used to enqueue Masonry (above). This will prevent layout errors due to images not loading before Masonry is done arranging elements.

If asked to do so again, this is how I would present Masonry to WordPress theme developers. There are many differences from the presentation I gave at WordCamp Las Vegas in December of last year. If you have any questions, please post them in the comments below.

Tags: , , ,

2 Responses to “Updated Masonry in WordPress”

  1. Hello Dan,

    Thank you so much for such a clear tutorial. I had been struggling with this, but with one quick change to my code (following your guidelines above), it all fell into place – literally!