3 Ways to Reset the WordPress Loop

WordPress does an excellent job of keeping track of what’s happening with the loop, but once you start customizing parameters and setting up multiple loops, it’s a good idea to explicitly reset them using one of three WordPress template tags. In this DiW post, we’ll explore these techniques to get a better understanding of when and how to use them in your WordPress themes.

wp_reset_postdata()

First up we have wp_reset_postdata, which restores the global $post variable to the current post in the main query. This is useful when using WP_Query to customize loops or create multiple loops on the same page. It looks like this:

<?php wp_reset_postdata(); ?>

This tag is nice and simple – it accepts no parameters and returns no values. It simply resets the post data after a custom query. So for example, let’s say we have a custom WP_Query loop in our theme’s header.php file, something like this:

This would display a random post in the header, but it will also change the main query object for any other loops on the page. Without the original query data available, the main posts loop contained in, say, index.php may produce unexpected results. Fortunately, we can use wp_reset_postdata to restore the query object to its original state.

To use wp_reset_postdata, just place after your custom loop(s). Here is our previous example with wp_reset_postdata to reset the loop:

When to use: best used after custom or multiple loops created with WP_Query.

wp_reset_query()

Next up we have the wp_reset_query function, which resets the query used with custom loops. It’s a simple function that accepts no parameters and returns no values. It looks like this:

<?php wp_reset_query(); ?>

Specifically, this function was created to prevent issues with query_posts, as indicated for the function in the wp-includes/query.php file:

Looking at the wp_reset_query function in query.php, we see that it uses the adjacent wp_reset_postdata function to restore the global $post variable to the current post in the main query:

So both wp_reset_query() and wp_reset_postdata() reset the query object by restoring the global $post variable, but wp_reset_query takes it a step further and actually destroys the previous query before doing so. This is important when using query_posts(), as seen in the following example:

When to use: best used after a query_posts loop to reset things after a custom query.

rewind_posts()

Last but not least, we have the rewind_posts function, which basically does what it says: rewinds the loop so you can re-use the same query. The function accepts no parameters, returns no values, and looks like this when used in your theme files:

<?php rewind_posts(); ?>

So to understand when to use rewind_posts(), let’s say we want to use the same query in two different locations on the page. We want to display post titles in the first loop and post content in the second loop. To re-use the same posts, we include rewind_posts after the first loop, like so:

So, while wp_reset_query and wp_reset_postdata reset the entire query object, rewind_posts simply resets the post count, as seen for the function in the wp-includes/query.php file:

When to use: best for re-using the same query on the same page.

Summary

Quick summary for future reference:

  • wp_reset_postdata() -> best used after custom or multiple loops created with WP_Query
  • wp_reset_query() -> best used after a query_posts loop to reset a custom query
  • rewind_posts() -> best for re-using the same query on the same page

I hope this is a useful round-up of when & how to reset/rewind the WordPress loop. Note that the WP Codex information on these functions is kinda thin, so feel free to share any tips or examples in the comments.

Leave a Reply

Your email address will not be published. Required fields are marked *

CAPTCHA