How to fix pagination for custom loops?

The Problem

By default, in any given context, WordPress uses the main query to determine pagination. The main query object is stored in the $wp_query global, which is also used to output the main query loop:

if ( have_posts() ) : while ( have_posts() ) : the_post();

When you use a custom query, you create an entirely separate query object:

$custom_query = new WP_Query( $custom_query_args );

And that query is output via an entirely separate loop:

if ( $custom_query->have_posts() ) : 
    while ( $custom_query->have_posts() ) : 
        $custom_query->the_post();

But pagination template tags, including previous_posts_link(), next_posts_link(), posts_nav_link(), and paginate_links(), base their output on the main query object, $wp_query. That main query may or may not be paginated. If the current context is a custom page template, for example, the main $wp_query object will consist of only a single post – that of the ID of the page to which the custom page template is assigned.

If the current context is an archive index of some sort, the main $wp_query may consist of enough posts to cause pagination, which leads to the next part of the problem: for the main $wp_query object, WordPress will pass a paged parameter to the query, based on the paged URL query variable. When the query is fetched, that paged parameter will be used to determine which set of paginated posts to return. If a displayed pagination link is clicked, and the next page loaded, your custom query won’t have any way to know that the pagination has changed.

The Solution

Passing Correct Paged Parameter to the Custom Query

Assuming that the custom query uses an args array:

$custom_query_args = array(
    // Custom query parameters go here
);

You will need to pass the correct paged parameter to the array. You can do so by fetching the URL query variable used to determine the current page, via get_query_var():

get_query_var( 'paged' );

You can then append that parameter to your custom query args array:

$custom_query_args['paged'] = get_query_var( 'paged' ) 
    ? get_query_var( 'paged' ) 
    : 1;

Note: If your page is a static front page, be sure to use page instead of paged as a static front page uses page and not paged. This is what you should have for a static front page

$custom_query_args['paged'] = get_query_var( 'page' ) 
    ? get_query_var( 'page' ) 
    : 1;

Now, when the custom query is fetched, the correct set of paginated posts will be returned.

Using Custom Query Object for Pagination Functions

In order for pagination functions to yield the correct output – i.e. previous/next/page links relative to the custom query – WordPress needs to be forced to recognize the custom query. This requires a bit of a “hack”: replacing the main $wp_query object with the custom query object, $custom_query:

Hack the main query object

  1. Backup the main query object: $temp_query = $wp_query
  2. Null the main query object: $wp_query = NULL;

  3. Swap the custom query into the main query object: $wp_query = $custom_query;

    $temp_query = $wp_query;
$wp_query   = NULL;
$wp_query   = $custom_query;

This “hack” must be done before calling any pagination functions

Reset the main query object

Once pagination functions have been output, reset the main query object:

$wp_query = NULL;
$wp_query = $temp_query;

Pagination Function Fixes

The previous_posts_link() function will work normally, regardless of pagination. It merely determines the current page, and then outputs the link for page - 1. However, a fix is required for next_posts_link() to output properly. This is because next_posts_link() uses the max_num_pages parameter:

<?php next_posts_link( $label , $max_pages ); ?>

As with other query parameters, by default the function will use max_num_pages for the main $wp_query object. In order to force next_posts_link() to account for the $custom_query object, you will need to pass the max_num_pages to the function. You can fetch this value from the $custom_query object: $custom_query->max_num_pages:

<?php next_posts_link( 'Older Posts' , $custom_query->max_num_pages ); ?>

Putting it all together

The following is a basic construct of a custom query loop with properly functioning pagination functions:

// Define custom query parameters
$custom_query_args = array( /* Parameters go here */ );

// Get current page and append to custom query parameters array
$custom_query_args['paged'] = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;

// Instantiate custom query
$custom_query = new WP_Query( $custom_query_args );

// Pagination fix
$temp_query = $wp_query;
$wp_query   = NULL;
$wp_query   = $custom_query;

// Output custom query loop
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) :
        $custom_query->the_post();
        // Loop output goes here
    endwhile;
endif;
// Reset postdata
wp_reset_postdata();

// Custom query loop pagination
previous_posts_link( 'Older Posts' );
next_posts_link( 'Newer Posts', $custom_query->max_num_pages );

// Reset main query object
$wp_query = NULL;
$wp_query = $temp_query;

Addendum: What About query_posts()?

query_posts() for Secondary Loops

If you’re using query_posts() to output a custom loop, rather then instantiating a separate object for the custom query via WP_Query(), then you’re _doing_it_wrong(), and will run into several problems (not the least of which will be pagination issues). The first step to resolving those issues will be to convert the improper use of query_posts() to a proper WP_Query() call.

Using query_posts() to Modify the Main Loop

If you merely want to modify the parameters for the main loop query – such as changing the posts per page, or excluding a category – you may be tempted to use query_posts(). But you still shouldn’t. When you use query_posts(), you force WordPress to replace the main query object. (WordPress actually makes a second query, and overwrites $wp_query.) The problem, though, is that it does this replacement too late in the process to update the pagination.

The solution is to filter the main query before posts are fetched, via the pre_get_posts hook.

Instead of adding this to the category template file (category.php):

query_posts( array(
    'posts_per_page' => 5
) );

Add the following to functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Test for category archive index
    // and ensure that the query is the main query
    // and not a secondary query (such as a nav menu
    // or recent posts widget output, etc.
    if ( is_category() && $query->is_main_query() ) {
        // Modify posts per page
        $query->set( 'posts_per_page', 5 ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

Instead of adding this to the blog posts index template file (home.php):

query_posts( array(
    'cat' => '-5'
) );

Add the following to functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Test for main blog posts index
    // and ensure that the query is the main query
    // and not a secondary query (such as a nav menu
    // or recent posts widget output, etc.
    if ( is_home() && $query->is_main_query() ) {
        // Exclude category ID 5
        $query->set( 'category__not_in', array( 5 ) ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

That way, WordPress will use the already-modified $wp_query object when determining pagination, with no template modification required.

When to use what function

Research this question and answer and this question and answer to understand how and when to use WP_Query, pre_get_posts, and query_posts().

Related Posts:

  1. How to fix pagination for custom loops?
  2. How to fix pagination for custom loops?
  3. How can I paginate this?
  4. How to fix pagination for custom loops?
  5. How to fix pagination for custom loops?
  6. Alternative layout the loop
  7. How to fix pagination for custom loops?
  8. How to fix pagination for custom loops?
  9. Multiple loop with pagination in same page
  10. Pagination not working with custom loop
  11. Remove the Homepage Query
  12. Pagination not working on home page
  13. Is `query_posts` really slower than secondary query?
  14. Are there any scenarios where the query_posts may be used?
  15. WordPress category & taxonomy loop with pagination
  16. How do I prevent one of two multiple loops from repeating on a second page?
  17. Transient not working for custom loops
  18. Previous and Next Post link doesn’t work
  19. Pagination adding extra posts only on page 2
  20. Transient pagination not working properly
  21. post loop causes wp_users and wp_usermeta DB queries for each users
  22. get_the_foo() in the loop – does it perform another query?
  23. If No Search Results, Show Posts from Alternate Search Query
  24. How to Loop within a Loop (Display Children and then Grandchildren)
  25. multiple loops with pagination on the same page
  26. How to paginate this custom loop? [duplicate]
  27. Make a custom loop inside single.php with pagination
  28. Why do I get `Call to a member function have_posts() on a non-object `? [closed]
  29. Pagination gives extra page with no results
  30. Create ONE callback for all page templates, post filter queries + paginated pages, triggering pagination via AJAX
  31. Loop posts only excluding first post
  32. Get Pagination (WP-PageNavi) not to work
  33. Loop after page content
  34. How to get an array of years from all of the search results, and use it to filter by year the paginated loop?
  35. Complex query and posts pagination
  36. Display most viewed post from last 30 days is not working correctly
  37. Query posts if meta key starts with
  38. 3 Posts in Loop, Show Stickies First
  39. Why only one post (and no pagination) on this variation of the loop?
  40. Query reset problem or flawed code to enable custom post type query
  41. Query last updated posts (posts updated in the last 24 hours)
  42. Is it possible to have pagination with an offset loop?
  43. Conditional query that displays on Woo product attribute pages
  44. Calling & display certain product category loop and pagination on the homepage
  45. Pagination for multiple loops
  46. How to display posts by vote count and if no value continue with latest posts with no votes?
  47. Pagination – works on local but not live dev!
  48. How do I paginate a get_posts() request inside another page loop (Paginating childpages)
  49. Split wordpress loop to multiple layouts
  50. Distribute Gallery Images Every nth in Loop
  51. Loop inside query
  52. How to exclude or filter password protected posts when using next_post_link() previous_post_link
  53. How to append a query string to pagination?
  54. How do I get my loop.php to properly paginate?
  55. First archive page with a few posts
  56. Pagination broken after using 2 loops to show content
  57. Pagination on custom post type on front-page.php
  58. get_delete_post_link() inside Loop stubbornly returns nothing
  59. Query posts only with actual text content (not including shortcode or images)
  60. Frontpage pagination by week
  61. How can this multiple loop have pagination as described?
  62. I am officially missing something about transient posts
  63. Display more than 10 posts on author.php file
  64. static page with multiple loops breaks post pagination
  65. Pagination for two loops
  66. Exclude posts based on an array
  67. Query post & loop problem.
  68. How do I set the Stewart Search Template to return only published posts in the result
  69. Why does my WP_Query pagination on a custom page.php only loads the homepage?
  70. Trying to get all links in my posts
  71. Custom Query with Sticky Posts
  72. Custom query pagination with php parameter as arg problem
  73. Pagination on a underscore custom theme
  74. Build a Page which shows the Oldest Post with specific Custom Field Value
  75. WordPress multiple loops with default pagination
  76. Query posts and display all dates in repeater field in chronological order
  77. Style first 3 posts differently and use a 2nd loop to get rest of posts / offset and pagination broken
  78. Custom loop not working in singular.php, working in other pages
  79. Show posts by tags excluding current post
  80. Strange problem with wp_get_attachment_image_src database (db) query count
  81. Next 10 posts data of currently viewing post in blog page
  82. Adding pagination to WP_Query [duplicate]
  83. Pagination not working with custom loop
  84. Get query result before posts are displayed?
  85. Why is my pagination showing up?
  86. Pagination not working with custom loop
  87. Combine Query and Select Database to create directory loop
  88. Pagination not working with custom loop
  89. Displaying posts limit: can’t get pagination to display [duplicate]
  90. Paged homepage – requirements?
  91. Home page loop with pagination problem
  92. wordpress showing all posts instead of date range
  93. WooCommerce custom loop pagination on front page
  94. posts_nav_link() not working on index.php
  95. repeating posts on 2nd page to posts
  96. Limitless amount of posts in custom archive page
  97. Same posts within a paginated page
  98. Insert multiple custom components after x-number of posts
  99. Query Loop Block: possible to restrict just child pages?
  100. Use Base-URL with Query-Loop
Hata!: SQLSTATE[HY000] [1045] Access denied for user 'divattrend_liink'@'localhost' (using password: YES)