Tutorial: Using jQuery Masonry with WordPress

Need help implementing Masonry? Hire me at Microlancer.

This is a short tutorial on integrating Masonry, the jQuery layout plugin, with your WordPress site. We will try to use that jQuery plugin to show a list of posts in a neatly stacked layout, similar to the one I have down here. Here’s an explanation about Masonry, from it’s home page:

Think of it as the flip side of CSS floats. Whereas floating arranges elements horizontally then vertically, Masonry arranges elements vertically then horizontally according to a grid. The result minimizes vertical gaps between elements of varying height, just like a mason fitting stones in a wall.

Here’s a visual explanation, which I took and edited to fit my layout. Pay attention to the numbers, which shows the order of the elements in your HTML code:

Understanding Masonry’s Behaviors

Using Masonry itself is pretty simple, but if it’s the first time you’re using it there can be some surprising behaviors, especially regarding element spacing. Let’s talk about that first.

Masonry allows for two different cases. First is where all elements have the same width, and you should use this:

$('#container').masonry({ singleMode: true });

The second case is where your elements have differend widths. Use:

$('#container').masonry({ columnWidth: 200 });

Where columnWidth is the width of the grid (in pixel). Masonry will then follow these two rules:

  1. Total element width = CSS width + padding-left + padding-right + border-left-width + border-right-width + margin-left + margin-right
  2. When using columnWidth, then all elements must be placed horizontally at an increment of columnWidth (e.g. for columnWidth: 200, elements will start at 0 or 200 or 400 pixels and so on). This might not be intuitive and does not work like CSS float:

    The first element has a total width of 190px and margin-right is 0. At the same time the second element has 0 margin-left, so you will probably expect both to stick to each other. However, since the columnWidth says 200px, then the second element is pushed further and starts at 200px instead.

    That will not be the case if we only have one width, though. The next element will be placed right next to the previous one according to the margin between both.

WordPress + Masonry

Okay, coding time. We’ll try to recreate my Latest Links area where all elements have the same width. First we enqueue jQuery and call the Masonry JS script in the theme’s header.php file.

<?php wp_enqueue_script('jquery'); ?>
<?php wp_head(); ?>
<script language="javascript" type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery.masonry.min.js"></script>

Make sure that wp_enqueue_script appears before wp_head, and the script call appears after it. Here’s a more detailed article on how to correctly enqueue jQuery in WordPress. My Masonry JS is located in a /js folder, yours might be different.

Next, we decide how the HTML will be structured. Mine’s like this:

<div id="linky"> 
  <div class="boxy"> 
    <!-- post content -->
  <div class="boxy"> 
    <!-- post content -->
</div> <!-- #linky -->

Pretty simple. “Linky” will be the container div that will call the Masonry function, and “boxy” will be the elements that will be stacked together. The CSS is where it’s important, you want to make sure the container width and the total element widths match. For example, if you want to have four columns of elements, each having a width + padding of 190px and a margin-right of 10px, then the container will be 200 x 4 = 800px:

#linky {
  width: 800px;
  #linky .boxy {
  width: 170px;
  padding: 10px;
  margin-right: 10px;
  margin-bottom: 10px;

Below is my PHP to generate the HTML, I’m using WP_Query to specifically fetch the latest 15 posts from my Links category:

<div id="linky">
      $linksPosts = new WP_Query();
  <?php while ($linksPosts->have_posts()) : $linksPosts->the_post(); ?>
  <div class="boxy">
    <div class="read">
    <h4><a href="<?php if(get_post_meta($post->ID, "url", true)) echo get_post_meta($post->ID, "url", true); else the_permalink(); ?>"><?php the_title(); ?></a></h4>
      <?php the_content('Read the rest of this entry &raquo;'); ?>               
  <?php endwhile; ?>

Note that since Masonry saves a lot of space compared to regular floats, you will usually need plenty of elements at once to fill your container (hence 15 in my case).

Now that everything is in place, the last thing to do is to add the Masonry function, preferably right after the script call in header.php:

<script language="javascript" type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery.masonry.min.js"></script>
<script type="text/javascript">
  $('#linky').masonry({ singleMode: true });

And we’re done. Scroll down a little bit (or click here) to see an example; the container and element widths are different from the example CSS above, but you get the general idea.


Need help implementing Masonry? Hire me at Microlancer.

You may also like...

28 Responses

  1. Hi, Thanks for the great write up. I have never even heard of Masonry before, but it looks amazing. Bookmarking this page… awesome!

  2. philippdatz says:

    waiting for mootools version

  3. Sid says:

    Wow .. Thnks for sharing .. :)


  4. Adam says:

    Bookmarked with Intent on using on the Theme I’m currently working on! – I saw something like this not long ago and lost it.

    Great Post :)

  5. Sunn says:

    jQuery Masonry for drupal also, http://drupal.org/project/views_fluidgrid

  6. How do you find enough time to write this blog ?!?

  7. ayush says:

    Nice :)

  8. Deck says:

    hei great tutorial you got here! thanks for sharing this precious

  9. geert baven says:

    Thanks for your explanation.
    Did you see the latest masonry update. How would you add filter into wordpress with either categories or pages?

  10. Kevin says:

    Thanks for your tutorial,but in header.php

    $(‘#linky’).masonry({ singleMode: true });
    maybe lack the

  11. Cameron Kuc says:

    Jquery is included in WP–>

    Shorter logic can be used to call masonry by eliminating “language” like so:

    <script type="text/javascript "src="/js/masonry.js”>


    Awesome tutorial — You have a great design aesthetic, thanks for this contribution.

  12. tom says:

    You’ve forgotten to close the element in the very last code snippet :)

  13. 23. Hello, I study your weblog and it is very fascinating. Actually, it makes me thirst and i want much more of your articles. Please, send me via my e-mail if you have new write-up posted.

  14. JC says:

    Forgive my ignorance as I try to figure this out. I’m just trying to understand how all the pieces fit together. I get the enqueue in the header.php and the css stuff. But I see two sets of html code and a script that I’m unclear on where to place. Would I use them in a page template, or in another template file? For my frontpage, should they just go in the index.php as a replacement for some of the existing code?


  15. Oliver says:

    doesn’t work for me. could be easier.

  16. Hi,

    How does masonry relate to images in wordpress?

    This is the site i’m working on

    However, i’m not sure how it deals with images?
    Is there a line of code that will grab the “Featured Image” from wordpress 3+ or do you simply throw your images in the excerpt field? ?


  17. Tana Glaze says:

    yeah i don’t know if i like our real estate agent… she doesn’t do things when she says she will and i’m all about a schedule.

  18. thanks ya atas artikelnya salam kenal

  19. neel says:

    Excellent tutorial. thanks for sharing this excellent tutorial. I will love to see more tutorials on your blog.

  20. Carolyn says:


    I am trying to follow this tutorial, have one quick question,

    where am i putting the .php script that you stated in your instructions? in my page template? or is that directly into the html?


  21. sam says:

    Ive got a problem with Chrome 9.0.597 (Win 7), the formatting seems not to work correctly, and the posts appear as one long column to the left of my content area. Firefox working great.

    Any ideas please?

    Thanks Sam

  22. sam says:


    The above page demonstrates my previous posting. The problem seems to happen only on webkit browsers: chrome and safari (Ive checked both mac and PC). IE and firefox both work fine. Ive seen somestuff about CSS/ JQUERY load order, could this be the issue? Ive tried using an earlier version of masonry (1.2.0), and verified that jquery is loading properly in wordpress using both wp_enqueue_script and static url methods. Jquery seems to be loading and working ok. It has to be a webkit issue.

    Please, any help would be so appreciated.

  23. vishal says:

    Hi Guys,
    I am trying to implement the masonry plugin on my blog http://www.Iamvishal.com but I can’t seem to get it working.

    Below is my code. Any clues as to what I am doing wrong ?

    $(window).load(function () {

    $(‘#content’).masonry({columnWidth: 185});




  1. May 24, 2010

    […] of using this masonry inside you wordpress themes, but if you need the tutorial you could visit wplover.com. I think he already explained a lot and it’s easy to learnt. What I’m going to say […]

  2. July 29, 2010
  3. September 29, 2010

    […] Tutorial Using jQuery Masonry With WordPress […]

  4. December 19, 2010

    […] est ici utilisée sur la page Blog note. & cet article est basé sur le tutoriel anglais de wplover.com. // ← Photo : Restauration complète […]

  5. April 20, 2011