Trusted WordPress tutorials, when you need them most.
Beginner’s Guide to WordPress
WPB Cup
25 Million+
Websites using our plugins
16+
Years of WordPress experience
3000+
WordPress tutorials
by experts

How to Use Masonry to Add Pinterest Style Post Grid in WordPress

Editorial Note: We earn a commission from partner links on WPBeginner. Commissions do not affect our editors' opinions or evaluations. Learn more about Editorial Process.

This is a guest post by Josh Pollock

The Pinterest-like grid display of posts has been a popular design for WordPress blog index pages for a while. It is popular not only because it mimics the look of the popular social media site, but also because it makes the best use of space on the screen. On a WordPress blog index, it allows each post preview to be the size it naturally needs to be, without leaving extra space.

In this tutorial, I will show you how to use the popular Masonry JavaScript Library to create cascading grid layouts for your blog index, as well as archive pages for your theme. I will address a few issues that you need to consider for mobile-optimization and how to solve them.

Screenshot of Masonry Grid Layout in WordPress

Note: This is an advanced level tutorial for those who feel comfortable editing WordPress themes and have sufficient HTML/CSS knowledge.

Step 1: Add Necessary Libraries To Your Theme

Update: WordPress 3.9 now includes the latest version of Masonry.

First you need to load Masonry into your theme, using this code:

if (! function_exists('slug_scripts_masonry') ) :
if ( ! is_admin() ) :
function slug_scripts_masonry() {
    wp_enqueue_script('masonry');
    wp_enqueue_style('masonry’, get_template_directory_uri().'/css/’);
}
add_action( 'wp_enqueue_scripts', 'slug_scripts_masonry' );
endif; //! is_admin()
endif; //! slug_scripts_masonry exists

This code simply loads masonry and makes it available to your theme’s template files (see our guide on how to properly add JavaScripts and Styles in WordPress). Also note that we are not adding jQuery as a dependency for either. One of the advantages of Masonry 3 is that it does not require jQuery, but can be used with it. In my experience, initializing Masonry without jQuery is more reliable, and opens up the possibility of skipping loading jQuery, which can help with both page load times and compatibility issues.

Step 2: Initialize The Javascript

This next function sets up Masonry, defines the containers that will be used with it and also makes sure everything happens in the right order. Masonry needs to do calculate the size of each of the items on the page in order to layout its grid dynamically. A problem I’ve run into with Masonry in many browsers is that Masonry will miscalculate the height of items with slow loading images, leading to overlapping items. The solution is to use imagesLoaded to prevent Masonry from calculating the layout until all images are loaded. This ensures proper sizing.

This is the function and action that will output the initialization script in the page footer:

if ( ! function_exists( 'slug_masonry_init' )) :
function slug_masonry_init() { ?>
<script>
    //set the container that Masonry will be inside of in a var
    var container = document.querySelector('#masonry-loop');
    //create empty var msnry
    var msnry;
    // initialize Masonry after all images have loaded
    imagesLoaded( container, function() {
        msnry = new Masonry( container, {
            itemSelector: '.masonry-entry'
        });
    });
</script>
<?php }
//add to wp_footer
add_action( 'wp_footer', 'slug_masonry_init' );
endif; // ! slug_masonry_init exists

The function is explained step by step with inline comments. What the Javascript function does is tell Masonry to look inside a container with the id “masonry-loop” for items with the class “masonry-entry” and to calculate the grid only after images are loaded. We set the outer container with querySelector and the inner with itemSelector.

Step 2: Create Masonry Loop

Instead of adding the HTML markup for Masonry directly to a template we are going to create a separate template part for it. Create a new file called “content-masonry.php” and add it to your theme. This will allow you to add the Masonry loop to as many different templates as you want.

In your new file you will add the code shown below. The markup is similar to what you would normally see for any content preview. You can modify it anyway you need to, just be sure that the outermost element has the class of “masonry-entry” that we set as the itemSelector in the last step.

<article class="masonry-entry" id="post-<?php the_ID(); ?>" <?php post_class(); ?> >
<?php if ( has_post_thumbnail() ) : ?>
    <div class="masonry-thumbnail">
        <a href="<?php the_permalink(' ') ?>" title="<?php the_title(); ?>"><?php the_post_thumbnail('masonry-thumb'); ?></a>
    </div><!--.masonry-thumbnail-->
<?php endif; ?>
    <div class="masonry-details">
        <h5><a href="<?php the_permalink(' ') ?>" title="<?php the_title(); ?>"><span class="masonry-post-title"> <?php the_title(); ?></span></a></h5>
        <div class="masonry-post-excerpt">
            <?php the_excerpt(); ?>
        </div><!--.masonry-post-excerpt-->
    </div><!--/.masonry-entry-details -->  
</article><!--/.masonry-entry-->

This markup has classes for each of its parts so you can add markup to match your theme. I like adding a nice, slightly rounded border to .masonry-entry. Another nice option is no border for .masonry-entry, but to give it a slight shadow. That looks particularly good when the post thumbnail extends the whole way to the border of the container, which can be accomplished by giving .masonry-thumbnail margins and paddings of 0 in all directions. You will want to add all of these styles in a file called masonry.css in your theme’s css directory.

Step 3: Add Masonry Loop To Templates

Now that we have our template part you can use it in any template in your theme you like. You might add it to index.php, but not category.php if you don’t want it used for category archives. If you only want it used on your theme’s home page, when its set to show blog posts, you would use it in home.php. Wherever you choose all you need to do is wrap your loop in a container with the id “masonry-loop” and add the template part into the loop using get_template_part(). Be sure to start the masonry loop container before while (have_posts() ).

For example, here is the main loop from twentythirteen’s index.php:

<?php if ( have_posts() ) : ?>

    <?php /* The loop */ ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <?php get_template_part( 'content', get_post_format() ); ?>
    <?php endwhile; ?>

    <?php twentythirteen_paging_nav(); ?>

<?php else : ?>
    <?php get_template_part( 'content', 'none' ); ?>
<?php endif; ?>

And here it is modified to get use our Masonry loop:

<?php if ( have_posts() ) : ?>
<div id="masonry-loop">
    <?php /* The loop */ ?>
    <?php while ( have_posts() ) : the_post(); ?>
        <?php get_template_part( 'content', 'masonry' ?>
    <?php endwhile; ?>
</div><!--/#masonry-loop-->
    <?php twentythirteen_paging_nav(); ?>

<?php else : ?>
    <?php get_template_part( 'content', 'none' ); ?>
<?php endif; ?>

Step 4: Set Responsive Widths of Masonry Items

There are several ways that you can set the width of each Masonry item. You can set the width using a number of pixels when you initialize Masonry. I’m not a fan of doing that since I use responsive themes and it requires some complex media queries to get things right on small screens. For responsive designs, I’ve found the best thing to do is set a width value for .masonry-entry with a percentage, based on how many items you want in a row and let Masonry do the rest of the math for you.

All this requires is dividing the 100 by the number of items you want to set the percentage in a simple entry in your theme’s style.css. For example, if you want four items in each row you could do this in your masonry.css file:

.masonry-entry{width:25%}

Step 5: Mobile Optimization

We could stop here, but I don’t think the end-result works incredibly well on small phone screens. Once you’re happy with how your theme looks with the new Masonry grid on your desktop, check it out on your phone. If you’re not happy about how it looks on your phone, then you will need to do a little work.

I don’t think there is enough room on a phone’s screen for everything we added to our content-masonry template part. Two good solutions available to you are to shorten the excerpt for phones or skip it entirely. Here is an extra function you can add to your theme’s functions.php to do that. Because I don’t think these issues are a problem on tablets, I am using a great plugin Mobble in all of the examples in this section to only make the changes on phones, not tablets. I am also checking to see if Mobble is active before using it and if necessary falling back to the more general mobile detection function wp_is_mobile which is built into WordPress.

if (! function_exists('slug_custom_excerpt_length') ) :
function slug_custom_excerpt_length( $length ) {
    //set the shorter length once
    $short = 10;
    //set long length once
    $long = 55;
    //if we can only set short excerpt for phones, else short for all mobile devices
    if (function_exists( 'is_phone') {
        if ( is_phone() ) {
            return $short;
        }
        else {
            return $long;
        }        
    }
    else {
        if ( wp_is_mobile() ) {
            return $short;
        }
        else {
            return $long;
        }
    }
}
add_filter( 'excerpt_length', 'slug_custom_excerpt_length', 999 );
endif; // ! slug_custom_excerpt_length exists

As you can see we start by storing the long excerpt length and short excerpt length in variables, since we will be using those values twice and we want to be able to change them from one place if we need to later on. From there we test if we can use Mobble’s is_phone(). If so we set the short excerpt for phones and the long excerpt if we are not. After that we do the same basic thing, but using wp_is_mobile, which will affect all mobile devices ,if is_phone() can’t be used. Hopefully the else part of this function will never be used, but it’s good to have a backup just in case. Once the excerpt length logic is set it just comes down to hooking the function to the excerpt_length filter.

Shortening the excerpt is one option, but we can also do away with it entirely with a simple process. Here is a new version of content-masonry, with the entire excerpt portion ommited on phones:

<article class="masonry-entry" id="post-<?php the_ID(); ?>" <?php post_class(); ?> >
<?php if ( has_post_thumbnail() ) : ?>
    <div class="masonry-thumbnail">
        <a href="<?php the_permalink(' ') ?>" title="<?php the_title(); ?>"><?php the_post_thumbnail('masonry-thumb'); ?></a>
    </div><!--.masonry-thumbnail-->
<?php endif; ?>
    <div class="masonry-details">
        <h5><a href="<?php the_permalink(' ') ?>" title="<?php the_title(); ?>"><span class="masonry-post-title"> <?php the_title(); ?></span></a></h5>
        <?php 
            //put the excerpt markup in variable so we don't have to repeat it multiple times.
            $excerpt = '<div class="masonry-post-excerpt">';
            $excerpt .= the_excerpt();
            $excerpt .= '</div><!--.masonry-post-excerpt-->';
//if we can only skip for phones, else skip for all mobile devices
            if (function_exists( 'is_phone') {
                if ( ! is_phone() ) {
                    echo $excerpt;
                }
            }
            else {
                if ( ! wp_is_mobile() ) {
                    echo $excerpt;
                }
            }
        ?>
    </div><!--/.masonry-entry-details -->  
</article><!--/.masonry-entry-->

This time we have are testing to see if we are not on a phone/ mobile device and if so we return the excerpt part of our loop. If we are on a phone/ mobile device we do nothing.

Another thing you might want to do is increase the width of the Masonry items, which reduces the number in a row, on mobile devices. In order to do this, we will add a different inline style to the header based on device detection. Since this function uses wp_add_inline_styles it will be dependent on a specific style sheet. In this case I’m using masonry.css, which you might want, for keeping your masonry styles separate. If you don’t end up using that you can use the handle from another, already registered stylesheet.

if ( ! function_exists ( 'slug_masonry_styles' ) ) :
function slug_masonry_styles() {
    //set the wide width
    $wide = '25%';
    //set narrow width
    $narrow = '50%';
    /**Determine value for $width**/
    //if we can only set narrow for phones, else narrow for all mobile devices
    if (function_exists( 'is_phone') {
        if ( is_phone() ) {
            $width = $narrow;
        }
        else {
            $width = $wide;
        }        
    }
    else {
        if ( wp_is_mobile() ) {
            $width = $narrow;
        }
        else {
            $width = $wide;
        }
    }
    /**Output CSS for .masonry-entry with proper width**/
    $custom_css = ".masonry-entry{width: {$width};}";
    //You must use the handle of an already enqueued stylesheet here.
    wp_add_inline_style( 'masonry', $custom_css );
}
add_action( 'wp_enqueue_scripts', 'slug_masonry_styles' );
endif; // ! slug_masonry_styles exists

This function eneuques the custom stylesheet, and then sets a value for width using what should now be very familiar logic. After that we create the $custom_css variable by passing the value for width into an otherwise regular looking bit of CSS with {$width}. After that we use wp_add_inline_style to tell WordPress to print our inline styles in the header whenever the Masonry stylesheet is being used and then we hook the whole function to wp_enqueue_scripts and we are done.

If you chose to combine your Masonry styles into an existing stylesheet, be sure to use the handle of that style sheet with wp_add_inline_style or your inline styles will not be included. I like to use wp_add_inline_style because I generally wrap the action hook for enqueueing Masonry in a conditional so it only gets added when needed. For example if I am only using Masonry on my blog index and archive pages I would do this:

if ( is_home() || is_archive() ) {
    add_action( 'wp_enqueue_scripts', 'slug_scripts_masonry' );
}

These last few examples should open up some other ideas in your brain. For example, you could use similar logic to skip Masonry altogether on a mobile device. Also wp_add_inline_style() is a lesser used, yet very helpful function as it allows you to programmatically set different styles based on any type of conditional. It can allow you to radically change the style of any element based on not only device detection, but the changes could also be based on which template is being used, or even if the user is logged in or not.

I hope you see these different changes I am making as an opportunity to get creative. Masonry and similar cascading grid systems have been popular for awhile now, so its time for some new twists on this popular idea. Show us in the comments what cool ways you’ve come up with for using Masonry in a WordPress theme.

A multi-purpose WordPress guy, Josh Pollock writes about WordPress, does theme development, serves as the community manager for the Pods Framework and advocates open source solutions for sustainable design.

Disclosure: Our content is reader-supported. This means if you click on some of our links, then we may earn a commission. See how WPBeginner is funded, why it matters, and how you can support us. Here's our editorial process.

Avatar

This post was written by a guest contributor. You can see their details in the post above. If you'd like to write a guest post for WPBeginner, then check out our Write for WPBeginner page for details. We'd love to share your tips with our community.

The Ultimate WordPress Toolkit

Get FREE access to our toolkit - a collection of WordPress related products and resources that every professional should have!

Reader Interactions

39 CommentsLeave a Reply

  1. Syed Balkhi says

    Hey WPBeginner readers,
    Did you know you can win exciting prizes by commenting on WPBeginner?
    Every month, our top blog commenters will win HUGE rewards, including premium WordPress plugin licenses and cash prizes.
    You can get more details about the contest from here.
    Start sharing your thoughts below to stand a chance to win!

  2. Gabi says

    Hi, i wanted to know if there is a way of using the masonry grid to show registered users. Any ideas?

  3. Neil says

    Just a quick note if you’re getting the “imagesLoaded” error, try adding the Javascript code after the wp_footer call in your footer.php.

    This work for me:

    Add to functions.php

    add_action( ‘wp_enqueue_scripts’, ‘slug_masonry’ );
    function slug_masonry( ) {
    wp_enqueue_script(‘masonry’); // note this is not jQuery
    }

    In your loop, make sure your div is:

    And the image class is:

    and then after wp_footer in your footer.php this:

    //set the container that Masonry will be inside of in a var
    var container = document.querySelector(‘#masonry-loop’);
    //create empty var msnry
    var msnry;
    // initialize Masonry after all images have loaded
    imagesLoaded( container, function() {
    msnry = new Masonry( container, {
    itemSelector: ‘.masonry-entry’
    });
    });

  4. Marisa Di Monda says

    Hi Andy I just tried this and I couldn’t get it to work. Everything is still running vertically in one column.
    Any solutions?

  5. Peter says

    did not work for me. i see only two images on my front page which are arranged underneath. don’t know where is the problem :(

  6. Eva says

    For some reason my posts will just all show just in rows like normal, not in masonry form, I’m not really sure how this can happen. Any ideas?

  7. jcbrmn06 says

    For anyone still having issues with this, I noticed that this code:

    //set the container that Masonry will be inside of in a var

    var container = document.querySelector(‘#masonry-loop’);

    //create empty var msnry

    var msnry;

    // initialize Masonry after all images have loaded

    imagesLoaded( container, function() {

    msnry = new Masonry( container, {

    itemSelector: ‘.masonry-entry’

    });

    });

    Was before the masonry JS library. Therefore you get the imagesLoaded error. Like Andy suggested below putting it in the header should fix it. Basically you just have to make sure the library has to come before this code.

  8. Andy Giesler says

    Thanks again for this tutorial, it really helped start me on my way.

    Even with everything in place, I saw intermittent problems where the tiles simply ran down the left of the page in a single column, and Firebug confirmed that sometimes the Masonry code didn’t execute. This happened only occasionally, and only in Firefox.

    It seemed that under certain load scenarios, there were probems with code trying to execute before the required files were loaded. I don’t think this was an imagesLoaded problem, since that has different symptoms.

    I fixed the problem as follows:

    1. The “slug_masonry_init” function places the masonry init code inline into the footer. I removed that whole function (as well as the add_action ‘wp_footer’ code) and moved the JS into an extenal file: masonry-init.js

    2. I wrapped the masonry init code in jQuery to take advantage of its document.ready ability. It’s unfortunate to pull in jQuery since this is the jQuery-free version of Masonry, but document.ready seemed necessary for the code to execute in all load scenarios.

    (function( $ ) {
    “use strict”;
    $(function() {

    });
    }(jQuery));

    3. I enqueued the scripts like this:

    wp_enqueue_script( ‘masonry’ );
    wp_enqueue_script( ‘jquery’ );
    wp_enqueue_script( ‘masonryInit’, get_stylesheet_directory_uri().’/js/masonry-init.js’, array( ‘masonry’, ‘jquery’ ) );

  9. Daniel Nikolovski says

    Done exactly as the tutorial says, wp 3.9.1.. imagesLoaded isn’t even being loaded. Some help would be highly appreciated

  10. Jenny Beaumont says

    I’m having trouble getting this to work…followed things accordingly, based on _s, but my columns don’t wrap – just get one long one. Have any css examples to go with? I’m obviously missing something. cheers!

  11. caratcake says

    I’m desperately confused. I performed every step down to the letter, and my site just goes blank. A problem with the functions file. My browser doesn’t even allude to which line causes any error, all I get is ”
    Server error
    The website encountered an error while retrieving (url) It may be down for maintenance or configured incorrectly.”

    The same happened for the WP Admin login page. I deleted functions.php in my theme folder, and the login screen was restored, but the front page was not. If you could give me any clues to what the problem might be, I would be very grateful. Regardless, many thanks for the tutorial and in depth explanations.

  12. Andy Giesler says

    In case this helps others to get the sample working:

    It wasn’t working for me even after I made the fix that others have noted — changing “function slug_masonry_exists()” to “function slug_masonry_init()”. The libraries were being loaded, but Masonry wasn’t doing its thing.

    Then I changed the wp_enqueue_script calls so that Masonry and imagesLoaded got loaded in the header instead of at the bottom.

    Suddenly everything worked.

    • Jean says

      Hi, i can´t figure out how do change the wp_enqueue_script. I will really appreciate if you can explain that in detail. Thanks!

  13. gabi says

    Hello, It doesn’t work for me I have this error message :
    ” Parse error: syntax error, unexpected T_ENDIF in…”…functions.php on line 17

    It means an error on the script from the 3td step. What did I miss ?

  14. Steven Gardner says

    The initialization script keeps being called before imagesloaded has been defined so I get

    Uncaught ReferenceError: imagesLoaded is not defined

    How can I make sure imagesLoaded is there first before I start to initialise things?

    • Violacase says

      imagesLoaded is called before enqueueing has been established. Give it a low priority so that it is called last, like:

      add_action( ‘wp_footer’, ‘slug_masonry_init’, 100000 );

      This did the trick for me.

      Nota: I think this article needs to be updated. Not only because of this issue.

  15. Kate says

    Thanks for this post. I am trying to set up a blog page with Masonry posts, but I’m snagged at step 1. Whenever I add the functions for adding the two libraries to my functions file, my site goes totally blank. Since I am developing in a subdirectory, I tried to make the paths to the js files absolute rather than relative, but that didn’t help. Any idea what I’m missing?

  16. Angie Lee says

    Hi,

    I’m getting this error: “ReferenceError: imagesLoaded is not defined” please help.

  17. Amitabha Ghosh says

    Thanks. It’s a great post and it is working for me. I am doing a template with this code and it is working perfect. But two obstacles I am facing
    1. I want to limit my posts in my index page so that it shows first 6 to 7 posts and below will be a button with “Load More” feature which when clicked shall load the other posts.

    2. I am trying to integrate infinite scroll javascript of Paul Irish but I couldn’t make it work. Any help??

    Thanks

  18. Ismar Hadzic says

    Well I followed all of your steps and I run on fatal error ” PHP Fatal error: Call to undefined function wp_enquqe_style() ” and i still don’t understand why wp_enquqe_style() i don’t understand why can you check that out.

  19. Aurélien Denis says

    Hi there!

    This post is great start but I found some mistakes…

    1/ You should use the_title_attribute() for the attribute title instead of the title
    2/ add_action( ‘wp_footer’, ‘slug_masonry_exists’ ); is the correct code and not add_action( ‘wp_footer’, ‘slug_masonry_init’ );

    Cheers!

  20. Ben Racicot says

    Can’t get this working with an infinite scroll setup in my $ajax success CB. Any advice would be great.

  21. Tomasz Bystrek says

    I was looking for this effect, but I did’t know how it is called and how to search for it, until now. I’ll definitely try it in one of my future project of photo blog. Thanks!

  22. Katrina Moody says

    Great post – wish it was around when I started working with Masonry on a theme a few weeks ago :D

    A couple variations – I created a new post-thumbnail image size to pull in so that both horizontal and vertical images would have equal attention within the Masonry pages – it’s fairly easy to change out the actual image for a new one (I did that at first, creating a new “entry-thumbnail” size and allowing unlimited length so that horizontal images would display properly). Then I just edited the post-thumbnail ;-)

    I also wrapped the post-thumbnail within an tag so that I could allow it to return to the post permalink (I changed that out to return the media file link so I could implement a lightbox effect – per a client’s request) so visitors could go directly to the post.

    I also added a hover effect to the post-thumbnail to indicate it was clickable :D

    Now I need to pick through what I’ve done and compare it to yours and see what I can improve with your knowledge (love the WordPress community!)

Leave A Reply

Thanks for choosing to leave a comment. Please keep in mind that all comments are moderated according to our comment policy, and your email address will NOT be published. Please Do NOT use keywords in the name field. Let's have a personal and meaningful conversation.