Integrating Isotope with WordPress

Isotope is a very powerful jQuery plugin that allows you to create sortable, filterable (I’m sure that’s a word) masonry layouts (although you can have other layouts as well). Isotope is free for personal use (a commercial license costs $25, and an organizational license $90).

In this tutorial I will show how to add the Isotope code and scripts to a  template. In my example, I will use the categories to filter a list of posts.

Update: I wrote a part 2 for this tutorial that shows how to use one category’s subcategories to filter posts.

  1. Download the script from the Isotope repository, and upload it to your theme’s folder (for example /js/libs/jquery.isotope.min.js)
  2. Add a list of categories that will serve as filters (following the filtering instructions in istotope):
  3. Make a custom  loop to load a bunch of blog post. Each blog posts must share a class (in my case, I used ‘item’), and additional classes to filter (from the list of categories from Setp 2):
  4. Go check. At this point your page should have a list with all your categories, and a bunch of posts. View the page source to make sure the blog posts have the proper classes (‘item’, plus all the categories it belongs to).
  5. Create a file with the necessary JavaScript to launch and set up Isotope, and place it in your theme folder (for example, /js/isotope.js):
  6. There is some optional, but recommended CSS that you should add to animate the filtering. Place a CSS file with the code in your theme folder (for example,  /css/isotope.css). Feel free to add additional styles to make your posts look nice:
  7. In functions.php, load the scripts and CSS:

That’s it!

86 Responses to “Integrating Isotope with WordPress”

  1. Jordan Shipman

    This is awesome. Searched everywhere for something that would work. Thank you very much.

    Do you know how you would modify the code or CSS so that the active filter appeared as a different color?

  2. Jordan Shipman

    Nevermind, figured that out 🙂 Modified the .selected class. Nice!

  3. Kent Budolfsen

    Great tutorial – works like a charm in Firefox – but I can’t get it to work in Safari, Chrome or Opera…. Do you have a solution for that.

    • Alicia Ramirez

      Hi Kent,

      It should work in all browsers. Are you developing locally? That could be an issue. If not, send me the URL, and I’ll take a look.

  4. Paedro FUnKensteiN

    Thanks for the article Alicia. The code you supplied for the filter/s, identifiers and the javascript got my Isotope based page up and running really fast. Thank you!

  5. john

    How could I use this with woocommerce using the subcategories as filters on the main category page.

  6. Joseph Bramall

    Hi, thanks for this post, it’s amazing. It’s exactly what I’v been looking for. Would yo be able to tell me how to target custom post types with custom fields though? Thanks again. x

  7. Scott

    Now a days WordPress is the powerful CMS for website design & development. we can maximum utilize it by using this type of plug in.

  8. Miles

    Thanks for taking the time to put this together, great step by step guide! Much appreciated!

  9. Anirudh

    Well written tutorial !!

    Alicia Ramirez, good work, I believe, people will be forever in need of Isotope wordpress integration tutorial.

  10. Joel

    Thank you!!! I modified the code to work with wookmark (a masonry like jquery plugin) and with just a few changes it works great.

  11. Joel

    Hi, thanks for the tutorial!

    Any chance you could expand on how to add BBQ Hash History so the back button works between filters?

  12. Gennaro

    Hi Alicia, thank you so much for this tutorial.

    All works but I have a doubt about the step number 5.

    I don’t understand the row 21: you set the variable optionSet then you don’t use it.

    Why do you do this? (I’m a newbie of jQuery).

  13. hel

    i am working with the Shortcodes Ultimate Plugin, where do i integrate the custom loop in my template.php?

    For example my loop

    • Alicia Ramirez

      I’ve never used that plugin, so I’m not sure how using the plugin affects the coding.

      In my example, I used a custom loop so that it can be anywhere in a template (except inside another loop, of course), without affecting other loops on it, and so you can customize it. You can integrate Isotope with a regular loop, though.

  14. Dedalos

    Hola Alicia, muchas gracias por tu código y tu tutorial.
    Despues de mucho buscar, ya lo tengo funcionando.
    Te invitaría a una cerveza!!!
    Muchas gracias de nuevo

  15. Denis

    big thanks for the great tutorial!
    I’ve almost managed to get it working, it looks like I got an issue with filtering (the filtering class are present and the good ones / but sth. is wrong 🙁 )
    Did I miss sth ?
    Any help, tips on where to look would be hugely appréciated 🙂

    • Alicia Ramirez

      Notice in line 8 of step 2 of the tutorial, where you are generating the list of filters, there is a . (period) as part of the value. In other words, the generated HTML would look like so: <li><a href='#' data-filter='.65' rel="nofollow">Bandes-annonces</a></li>

  16. Henrik Stjerne

    Hi and thank you for this tutorial.

    I have followed the steps, but I can get it to work. I get the list of categories and posts, but nothing happends when I click the categories?

    • Alicia Ramirez

      Without looking at your setup it’s hard to tell, but perhaps the scripts aren’t loading (make sure the paths on step 7 point to where you placed the scripts in your theme).

      • Henrik Stjerne

        Hi and thanks for the reply.

        I managed to get it working perfectly, it was the paths. I have another problem however. My blog has many posts and I display 20 on each page (1,2,3,4 etc). However, the same 20 posts (latests) are shown on all pages. Any fixes? Thanks agaian

        • Henrik Aagaard


          I have tried this without any luck, I am a bit unsure where to add this code, is it in the loop? My mother theme was paged in the first place, but after editing the loop to your Isotope code, it does not work anymore. Thanks

  17. A

    Hey, great tut! Do you or anyone here have a demo of your final result? Super anxious to see what it actually looks like. Thanks in advance!

  18. Fernon

    Hi Alicia,

    I’ve got a question. I love the way you explained everything, its very clear. But Everything is displayed on my site including the categories, but when I click on a category nothing happens. The link is #. Did I miss something? Thanks!

    • Alicia Ramirez

      It’s hard to tell without looking at your code, but a common mistake is missing the a period (.) in the data-filter. Make sure the links look something like this: <li><a href='#' data-filter='.something' rel="nofollow">Something</a></li>

  19. Jose

    Hola Alicia, great tutorial !!!

    What should I do in order to use isotope for arranging items with different heights (thumbnails/featured images in CPT archive template) and not for filtering ? Thanks

    • Alicia Ramirez

      If you don’t want to filter, skip step one. If you are using it in an archive, you probably don’t need a custom loop (step 2), simply use a regular loop. In my example, in step 3, I used the masonry layout mode, which should accommodate items of different heights, and widths. You can learn about additional layout modes here:

  20. Quentin

    Thanks a lot Alicia ! It’s works ! I just have a short question, is it possible to force the filters to act only on the primary page ? When I’m in another page I can’t go back to the filtered content.

  21. Tony

    Good Evening,
    i’d like how to sort instead of to filter posts. Thank you.

  22. John

    Thanks Alicia, this a great tutorial!!

    Is there a way to have it work with categories and tags. At the moment it works with either, but not both even when I use this:

    $termsArray = get_the_terms( $post->ID, "project_category" , "tag");

    It seems to sort but when the tag filters are clicked the posts are not showing. If I switch and have tags first like this: $termsArray = get_the_terms( $post->ID, “tag”, “project_category”); then the tags work and categories disappear when the category filter buttons are clicked.

    Thanks for your help.

  23. pipoulito

    i created my custom taxonomy : “style”, but when i replace “category” by “style” there’s nothing…could i have help please ?

    • Alicia Ramirez

      Does it list your styles? If it does, make sure to also change “category” for “style” on line 5 on step 3. If you have “style” in both places, then it may be a typo, or that no posts have a style applied to them… Without looking at your code or setup, it’s hard to tell. Try posting your code on

  24. loic

    Is it possibleto display 10 posts per page and using pagination with isotope ?
    I try to get both pagination and isotope filtering but when i click on page 2, I stille get 10 first posts.


    • Alicia Ramirez

      This may not be an issue with Isotope, but of how pagination is being implemented. Make sure to change the loop on step 3 from $the_query = new WP_Query( 'posts_per_page=50' ); to
      $paged = ( get_query_var('page') ) ? get_query_var('page') : 1;
      $the_query = new WP_Query('posts_per_page=10&paged=' . $paged ) );

  25. loic

    Thank you Alicia!
    One more thing, I struggle to get link (cursor pointer) of “everything” when the first category is selected.
    Are you experiencing the same?


  26. Hussy

    Hi Alicia, I implemented it in my theme and it like charm now i want to add it through shortcode. can you help me with that. i tried everything is working but filters are not working even data-filter and portfolio list have same class. Here is my code:


  27. ottie

    Great Alicia,
    Your code comments helped me to modify the code by using Types and Views on WP. One issue though: when the page is initialized and all results are given, they are stacked.
    When a category is pressed, they form a grid. So I guess it has something to do with the initialisation of the page? Any clue?
    Thanks for the understandable explanation.


  28. Adam

    I’d like to be able to show the category description somewhere on the page after a sort is made. Do you know of a way to do that?

  29. olivier

    Hi, first thanks so much for this tutorial and example. I’ve setup the posts filtering in an archive page with foundation block grid and it work great (some styling has to be done). Now i’ve got a question :
    I’ve got a “category” widget on my single page sidebar and when i click on a given category in this widget, i want the archive page open with the posts allready filtered. Do you think it can be done ?
    Thanks a lot for your advice.

  30. Adam

    Is there a way o you can choose which categories show up in the filters? For example enter slug-ids rather than all categories? desperate and i cant find a fix