Tutorial: Using jQuery Masonry with WordPress

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:

Total element width = CSS width + padding-left + padding-right + border-left-width + border-right-width + margin-left + margin-right
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> 
 
  <div class="boxy"> 
    <!-- post content -->
  </div> 
 
  ...
 
</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">
 
  <?php
      $linksPosts = new WP_Query();
      $linksPosts->query('showposts=15&cat=7');
  ?>
  <?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;'); ?>               
    </div>
  </div>
  <?php endwhile; ?>
 
</div>

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">
jQuery(document).ready(function($){
  $('#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.

Resources

The jQuery Masonry home page
Interactive CSS Box Model Demo, to help understand how element width is measured.
Mortar theme demo. Mortar is a theme by Woo Themes that uses Masonry; good example if you want to view-source.
jQuery Masonry screencast at Teach Me To Code.
Hacker News thread about Masonry. Discusses Masonry’s weaknesses worth thinking about.
How to correctly enqueue JQuery in WordPress at DigWP.

Development

4 May 2010