How to paginate custom WP_Query loops correctly without breaking global state?

‘next_text’ => ‘‘ . __( ‘Next page’, ‘textdomain’ ) . ‘‘,

‘before_page_number’ => ‘‘ . __( ‘Page’, ‘textdomain’ ) . ‘ ‘,

) );

else :

// No posts found

endif;

// No wp_reset_postdata() needed here because we modified the main query, we didn’t create a new one.

“`

When to use the_posts_pagination():

• Always with the main query.
• It automatically detects the current page and total pages based on $wp_query.
• It respects your permalink structure.

Method 3: Handling Multiple Custom Queries on One Page

What if you have a page with two or more separate custom queries, each needing its own pagination? This scenario combines elements of Method 1.

The Challenge

The main challenge here is that paginate_links() needs to know which query it should be generating links for. If you run two WP_Query instances and then call paginate_links() twice, both will likely use the same paged variable from the URL (or default to 1), leading to both queries trying to paginate based on the same page number, which isn’t what you want.

Solution: Unique paged Variables and Query String Parameters

You need distinct URL parameters for each paginated query.

Step 1: Define Unique paged Variables

Instead of just paged, use something like event_paged and resource_paged.

First, register these custom query variables so WordPress knows to expect them. Place this in your functions.php:

“`php

function add_custom_query_vars( $vars ) {

$vars[] = ‘event_paged’;

$vars[] = ‘resource_paged’;

return $vars;

}

add_filter( ‘query_vars’, ‘add_custom_query_vars’ );

“`

Now, when retrieving the current page number for each query:

“`php

$event_paged = ( get_query_var( ‘event_paged’ ) ) ? get_query_var( ‘event_paged’ ) : 1;

$resource_paged = ( get_query_var( ‘resource_paged’ ) ) ? get_query_var( ‘resource_paged’ ) : 1;

“`

Step 2: Create Custom WP_Query Instances

“`php

// Query 1: Events

$args_events = array(

‘post_type’ => ‘event’,

‘posts_per_page’ => 5,

‘paged’ => $event_paged,

);

$events_query = new WP_Query( $args_events );

// Query 2: Resources

$args_resources = array(

‘post_type’ => ‘resource’,

‘posts_per_page’ => 8,

‘paged’ => $resource_paged,

);

$resources_query = new WP_Query( $args_resources );

“`

Step 3: Loop Through Each Query and Generate Pagination

This requires careful construction of the base and format parameters for paginate_links().

“`php

// Events Section

if ( $events_query->have_posts() ) :

echo ‘

Upcoming Events

‘;

while ( $events_query->have_posts() ) : $events_query->the_post();

// Display event post

endwhile;

if ( $events_query->max_num_pages > 1 ) {

$big = 999999999;

// Build the base URL for events

$current_url = get_pagenum_link(1); // Start with the clean current URL

// If there’s already a ‘resource_paged’ in the URL, preserve it

if (get_query_var(‘resource_paged’)) {

$current_url = add_query_arg(‘resource_paged’, get_query_var(‘resource_paged’), $current_url);

}

echo paginate_links( array(

‘base’ => esc_url( add_query_arg( ‘event_paged’, ‘%#%’, $current_url ) ),

‘format’ => ”, // Since we’re embedding event_paged, format can be empty

‘current’ => max( 1, $event_paged ),

‘total’ => $events_query->max_num_pages,

‘prev_text’ => ‘« Prev Events’,

‘next_text’ => ‘Next Events »’,

) );

}

wp_reset_postdata(); // Reset after the events loop

endif;

// Resources Section

if ( $resources_query->have_posts() ) :

echo ‘

Helpful Resources

‘;

while ( $resources_query->have_posts() ) : $resources_query->the_post();

// Display resource post

endwhile;

if ( $resources_query->max_num_pages > 1 ) {

$big = 999999999;

// Build the base URL for resources

$current_url = get_pagenum_link(1); // Start with the clean current URL

// If there’s already an ‘event_paged’ in the URL, preserve it

if (get_query_var(‘event_paged’)) {

$current_url = add_query_arg(‘event_paged’, get_query_var(‘event_paged’), $current_url);

}

echo paginate_links( array(

‘base’ => esc_url( add_query_arg( ‘resource_paged’, ‘%#%’, $current_url ) ),

‘format’ => ”, // Format can be empty here too

‘current’ => max( 1, $resource_paged ),

‘total’ => $resources_query->max_num_pages,

‘prev_text’ => ‘« Prev Resources’,

‘next_text’ => ‘Next Resources »’,

) );

}

wp_reset_postdata(); // Reset after the resources loop

endif;

“`

Key Difference with paginate_links for multiple queries:

• add_query_arg(): This function is crucial for constructing the base URL for each pagination. It allows you to add or update specific query parameters while preserving others in the URL.
• format parameter: We set format to an empty string. Since we’re explicitly building the query string with add_query_arg, paginate_links doesn’t need to append ?paged=%#% or /page/%#%. It will just replace the # in our base URL directly.
• Preserving other paged variables: When building the base for one query’s pagination, we need to ensure that if the other query’s paged variable is present in the URL, it’s carried over. This is done by checking get_query_var() and adding it back using add_query_arg().

This method gives each pagination mechanism its own independent set of URL parameters, allowing them to work in parallel without interference.

Essential Clean-up: wp_reset_postdata() and wp_reset_query()

These two functions are your best friends when dealing with WordPress queries, especially when you’re working with custom loops.

wp_reset_postdata()

• Purpose: Restores the global $post variable to the post that was active before a custom loop ($custom_query->the_post()) modified it.
• When to use it: Always use this after a custom WP_Query loop where you’ve called $custom_query->the_post(). If you don’t, any subsequent template tags like the_title(), get_the_ID(), etc., will refer to the last post from your custom loop instead of the main query’s current post.
• Analogy: Think of it like taking focus away from your custom content and putting it back on the main content of the page.

wp_reset_query()

• Purpose: Resets the $wp_query object and global $post to the original main query for the current request.
• When to use it: You generally do not need wp_reset_query() if you are correctly using new WP_Query() for your custom loops and wp_reset_postdata() afterward. wp_reset_query() is typically used if you’ve directly modified the global $wp_query object (which is generally discouraged outside of pre_get_posts).
• Warning: Misusing wp_reset_query() can sometimes cause more problems than it solves, as it can be overly aggressive. Stick to wp_reset_postdata() for custom new WP_Query instances.

In summary:

• For new WP_Query() instances: Always use wp_reset_postdata() after your loop.
• For pre_get_posts modifications: No reset functions are needed, as you are directly modifying the main query.
• Avoid wp_reset_query() unless you have a very specific reason and understand its implications.

By following these methods and understanding the differences between manipulating the main query and instantiating custom ones, you can correctly paginate your custom WordPress content without breaking the global state, ensuring a smooth experience for both you and your users.