Skip to content
geekerhub

How to Integrate Isotope with WordPress Step by Step

By ali 10 min read

Integrating Isotope with WordPress to create a category-filtered Masonry post grid

Isotope is a JavaScript library that makes it easy to create filterable and sortable content layouts. It is especially useful when you want to display WordPress posts in a Masonry-style grid and allow visitors to filter them by category.

For example, imagine you have a blog with different categories such as WordPress, PHP, Tutorials, and Plugins. Instead of displaying every post in one long list, you can create a grid where visitors select a category and instantly see the matching posts without reloading the page.

In this tutorial, we will integrate the Isotope JavaScript library with WordPress using PHP, jQuery, and WP_Query.

We will use the default WordPress post post type and its built-in category taxonomy. You can adapt the same approach for pages or custom post types by changing the post type and taxonomy.

What We Will Build

Our WordPress Isotope integration will include the following features:

  • Load the Isotope JavaScript library in WordPress.
  • Retrieve WordPress post categories dynamically.
  • Display categories as clickable filter buttons.
  • Fetch posts using WP_Query.
  • Add category classes to each post item.
  • Initialize Isotope with the Masonry layout.
  • Filter posts without reloading the page.

The process is simple: WordPress generates the post and category HTML using PHP, while Isotope handles the layout and filtering in the browser.

Step 1: Download and Enqueue the Isotope Library

First, we need to load the Isotope library into our WordPress theme.

You can download Isotope from the official Isotope website or use a CDN if you prefer.

For this example, download the packaged Isotope file named:

isotope. pkgd. min. js

Create a folder named js inside your active child theme and place the downloaded file there.

Your file structure should look like this:

your-child-theme/
    functions.php
    js/
        isotope.pkgd.min.js

Now add the following code to your child theme’s functions.php file:

function gh_enqueue_isotope_scripts() {

    wp_enqueue_script(
        'isotope',
        get_stylesheet_directory_uri() . '/js/isotope.pkgd.min.js',
        array( 'jquery' ),
        '3.0.6',
        true
    );

    wp_enqueue_script(
        'gh-isotope-init',
        get_stylesheet_directory_uri() . '/js/isotope-init.js',
        array( 'jquery', 'isotope' ),
        '1.0.0',
        true
    );
}

add_action( 'wp_enqueue_scripts', 'gh_enqueue_isotope_scripts' );

How this code works:

  • wp_enqueue_script() loads the Isotope JavaScript file.
  • get_stylesheet_directory_uri() points to the active theme or child theme directory.
  • array( 'jquery' ) tells WordPress that jQuery is a dependency.
  • array( 'jquery', 'isotope' ) ensures the initialization script loads after jQuery and Isotope.
  • The final true argument requests that the scripts load in the footer.

We are using one packaged Isotope file instead of loading both the regular and minified files. The packaged file includes the required Isotope components for this example.

Step 2: Display WordPress Categories as Filter Buttons

Next, we need to retrieve the categories assigned to our WordPress posts and display them as filter buttons.

We will use the WordPress get_terms() function to retrieve the categories dynamically.

Add the following code where you want the category filters to appear in your template:

<?php
$terms = get_terms(
    array(
        'taxonomy'   => 'category',
        'hide_empty' => true,
    )
);
?>

<?php if ( ! is_wp_error( $terms ) && ! empty( $terms ) ) : ?>

    <ul id="isotope-filter">

        <li>
            <a href="#" data-filter="*" class="selected">
                All
            </a>
        </li>

        <?php foreach ( $terms as $term ) : ?>

            <li>
                <a
                    href="#"
                    data-filter=".<?php echo esc_attr( $term->slug ); ?>"
                >
                    <?php echo esc_html( $term->name ); ?>
                </a>
            </li>

        <?php endforeach; ?>

    </ul>

<?php endif; ?>

How Does This Code Work?

1. Retrieve categories:

$terms = get_terms(
    array(
        'taxonomy'   => 'category',
        'hide_empty' => true,
    )
);

This retrieves categories that have at least one published post associated with them.

2. Add the All filter:

<a href="#" data-filter="*" class="selected">All</a>

The * selector tells Isotope to display all items.

3. Generate category filters:

data-filter=". <?php echo esc_attr($term ->slug);
?> "

Each category gets a filter based on its slug. For example, a category with the slug wordpress will generate this filter:

data-filter=".wordpress"

Isotope will use this class selector to display matching posts.

Step 3: Retrieve WordPress Posts and Create the Masonry Grid

Now we need to display the posts inside a container that Isotope can control.

We will use WP_Query to retrieve posts and get_the_terms() to get their assigned categories.

Add the following code below the category filter in your template:

<?php

$args = array(
    'post_type'      => 'post',
    'post_status'    => 'publish',
    'posts_per_page' => -1,
);

$the_query = new WP_Query( $args );

if ( $the_query->have_posts() ) :
?>

    <div id="isotope-masonry">

        <?php
        while ( $the_query->have_posts() ) :
            $the_query->the_post();

            $post_classes = array( 'item' );

            $post_terms = get_the_terms(
                get_the_ID(),
                'category'
            );

            if ( ! empty( $post_terms ) && ! is_wp_error( $post_terms ) ) {

                foreach ( $post_terms as $term ) {
                    $post_classes[] = $term->slug;
                }
            }
        ?>

            <div class="<?php echo esc_attr( implode( ' ', $post_classes ) ); ?>">

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

                    <a href="<?php the_permalink(); ?>">
                        <?php the_post_thumbnail( 'medium' ); ?>
                    </a>

                <?php endif; ?>

                <h3>
                    <a href="<?php the_permalink(); ?>">
                        <?php the_title(); ?>
                    </a>
                </h3>

                <?php the_excerpt(); ?>

            </div>

        <?php endwhile; ?>

    </div>

<?php
endif;

wp_reset_postdata();
?>

Understanding the Post Query

1. Fetch WordPress posts:

$args = array(
    'post_type'      => 'post',
    'post_status'    => 'publish',
    'posts_per_page' => -1,
);

$the_query = new WP_Query( $args );

This query retrieves all published posts. The posts_per_page value of -1 means that WordPress will retrieve all matching posts. For websites with many posts, use pagination or a reasonable limit to avoid loading too much content at once.

2. Retrieve category terms:

$post_terms = get_the_terms(
    get_the_ID(),
    'category'
);

This retrieves the categories assigned to the current post.

3. Generate CSS classes:

$post_classes = array( 'item' );

foreach ( $post_terms as $term ) {
    $post_classes[] = $term->slug;
}

Each post gets the item class along with its category slugs.

For example, if a post belongs to the WordPress and Tutorials categories, its HTML class will look like this:

<div class="item wordpress tutorials">

These category classes allow Isotope to identify which posts should appear when a visitor selects a filter.

4. Restore the original WordPress query:

wp_reset_postdata();

Always call this after a custom WP_Query loop. It restores the global post data so that other template functions work correctly.

Step 4: Initialize Isotope Using jQuery

We have now loaded the library, created the category filters, and displayed the WordPress posts.

The next step is to initialize Isotope and connect the filter buttons to the Masonry grid.

Create a JavaScript file named isotope-init.js inside your theme’s js folder.

Add the following code:

jQuery(function ($) {

    var $grid = $('#isotope-masonry').isotope({
        itemSelector: '.item',
        layoutMode: 'masonry'
    });

    $('#isotope-filter').on('click', 'a', function (event) {

        event.preventDefault();

        var filterValue = $(this).attr('data-filter');

        $('#isotope-filter a').removeClass('selected');

        $(this).addClass('selected');

        $grid.isotope({
            filter: filterValue
        });

    });

});

How Does the jQuery Code Work?

1. Initialize the Isotope grid:

var $grid = $('#isotope-masonry').isotope({
    itemSelector: '.item',
    layoutMode: 'masonry'
});

This tells Isotope which container to manage. The itemSelector identifies individual posts, while layoutMode: 'masonry' enables the Masonry layout.

2. Listen for filter clicks:

$('#isotope-filter').on('click', 'a', function (event) {
    event.preventDefault();
});

This listens for clicks on the category filter links and prevents the browser from following the placeholder URL.

3. Get the selected filter:

var filterValue = $(this).attr('data-filter');

This retrieves the filter value from the selected link. It could be * for all posts or a category selector such as .wordpress.

4. Apply the filter:

$grid.isotope({
    filter: filterValue
});

Isotope updates the grid and displays only the matching posts without reloading the page.

Step 5: Add Basic CSS Styling

Isotope handles filtering and layout calculations, but you still need CSS to control the appearance of your grid.

Add the following CSS to your child theme’s stylesheet:

#isotope-filter {
    display: flex;
    flex-wrap: wrap;
    gap: 10px;
    list-style: none;
    margin: 0 0 25px;
    padding: 0;
}

#isotope-filter a {
    display: inline-block;
    padding: 8px 16px;
    background: #f1f1f1;
    color: #333;
    text-decoration: none;
    border-radius: 4px;
}

#isotope-filter a.selected,
#isotope-filter a:hover {
    background: #2271b1;
    color: #fff;
}

#isotope-masonry {
    width: 100%;
}

#isotope-masonry .item {
    width: 31%;
    margin-bottom: 20px;
    padding: 15px;
    box-sizing: border-box;
    background: #fff;
    border: 1px solid #eee;
    border-radius: 6px;
}

#isotope-masonry .item img {
    display: block;
    width: 100%;
    height: auto;
}

#isotope-masonry .item h3 {
    margin: 12px 0;
}

@media (max-width: 768px) {
    #isotope-masonry .item {
        width: 48%;
    }
}

@media (max-width: 480px) {
    #isotope-masonry .item {
        width: 100%;
    }
}

Adjust the item widths, spacing, colors, and typography to match your website design.

Note: If your post cards contain images that load after Isotope initializes, the Masonry positions may need to be recalculated. You can use the Isotope imagesLoaded integration or trigger a layout update after the images finish loading.

Step 6: Test the WordPress Isotope Integration

After completing the previous steps, open the page where you added the Isotope grid.

Check the following:

  1. Confirm that the posts are displayed in a Masonry-style grid.
  2. Click the All filter and verify that every post appears.
  3. Select a category and check whether only matching posts remain visible.
  4. Select another category and confirm that the grid updates correctly.
  5. Test the layout on desktop, tablet, and mobile screens.
  6. Check the browser console for JavaScript errors.

If the filters do not work, check that the category slugs in the post classes match the values in the filter buttons. Also confirm that the Isotope script is loading successfully and that jQuery is available.

Using Isotope with a Custom Post Type

The same approach can also be used with custom post types. You only need to change the post type in your WP_Query arguments and use the taxonomy registered for that post type.

For example, if your custom post type is named portfolio and its taxonomy is portfolio_category, update the query like this:

$args = array(
    'post_type'      => 'portfolio',
    'post_status'    => 'publish',
    'posts_per_page' => -1,
);

$the_query = new WP_Query( $args );

When retrieving the terms, use the custom taxonomy:

$post_terms = get_the_terms(
    get_the_ID(),
    'portfolio_category'
);

You should also update the category filter query to retrieve terms from portfolio_category instead of the default category taxonomy.

Make sure the custom taxonomy is registered for the custom post type before using it.

Common Problems and Solutions

1. Isotope Is Not Loading

Check the browser console and WordPress script URLs. Make sure the Isotope file exists in the specified theme folder and that it is enqueued correctly.

2. Category Filters Are Not Working

Check whether the category slug in data-filter matches the CSS class assigned to each post. A mismatch will prevent Isotope from finding the correct items.

3. Masonry Items Overlap

This can happen when images load after Isotope calculates the layout. Recalculate the layout after images finish loading or use an image-loading helper such as imagesLoaded.

4. JavaScript Errors Appear in the Console

Make sure jQuery and Isotope load before your initialization script. Check the dependency array in wp_enqueue_script() and avoid loading multiple conflicting versions of the library.

5. The Grid Loads Too Many Posts

If your website contains hundreds of posts, avoid using posts_per_page => -1. Set a suitable post limit or implement pagination or an AJAX-based loading system.

Frequently Asked Questions

1. What is Isotope in WordPress?

Isotope is a JavaScript library that helps create filterable, sortable, and dynamic grid layouts. In WordPress, it can be used to display posts, pages, or custom post types in a category-based grid.

2. Can I use Isotope with WordPress categories?

Yes. You can retrieve WordPress categories using get_terms(), add category slugs to filter buttons, and assign the same slugs as CSS classes to the post items. Isotope uses these selectors to filter the grid.

3. Can I integrate Isotope with a custom post type?

Yes. Use WP_Query with your custom post type and retrieve terms from the taxonomy registered for that post type. The same filtering approach can then be applied.

4. Do I need jQuery to use Isotope?

No. Isotope can be used with regular JavaScript. This tutorial uses jQuery because WordPress provides jQuery as a registered script dependency and it makes the filter click handling straightforward.

5. Can Isotope filter posts without reloading the page?

Yes. Isotope performs filtering in the browser using the category classes already present in the HTML. Visitors can select different filters without a page refresh.

Final Thoughts

Integrating Isotope with WordPress is a practical way to create category-based post grids and Masonry layouts. WordPress handles the data retrieval through PHP and WP_Query, while Isotope manages the visual layout and filtering through JavaScript.

Once the integration is complete, you can reuse the same approach for blog posts, portfolio items, products, or custom post types. You can also extend it with AJAX loading, search filters, sorting, and custom layouts as your project grows.

Start with the basic category filter and Masonry grid, test it with your WordPress content, and then add more features when needed.

Related guides