Introduction
WordPress pagination is a powerful feature that allows you to split your content into multiple pages, improving user experience and navigation. This article will guide you through the steps to implement built-in pagination with the WP_Query
class.
Setting Up Pagination with WP_Query
Create a custom query
Use the WP_Query
class to set up your custom query. The paged
parameter controls which page of results is displayed.
$query = new WP_Query([ 'posts_per_page' => 5, 'paged' => get_query_var( 'paged', 1 ), ]);
The get_query_var
function retrieves the value of a query variable in the WP_Query
class.
get_query_var( string $query_var, mixed $default_value = "" ): mixed
Loop through posts
After creating a query using the WP_Query
class, the next step is to check if any posts were found and process them. If posts are available, we use a loop to iterate through the posts and display the desired information.
if ( $query->have_posts() ) { while ( $query->have_posts() ) { $query->the_post(); // Output the post (e.g., the_title(), the_content(), etc.) } }
The while
loop runs as long as there are posts found by the query. The the_post()
function sets up the current post for display inside the loop. You can use standard WordPress functions here to display the title, content, thumbnails, and other post data.
After the post loop, it’s important to reset the global post data to prevent conflicts with other queries on the page:
wp_reset_postdata();
Output pagination links
Now let’s break down the code that outputs pagination links. Pagination is essential to allow users to easily navigate between pages of posts.
echo paginate_links([ 'total' => $query->max_num_pages, 'current' => max( 1, get_query_var( 'paged', 1 ) ), ]);
total
: Thetotal
parameter indicates the total number of pages. We get this value from the$query->max_num_pages
property, which automatically calculates how many pages are needed to display all posts, based on theposts_per_page
setting (for example, 5 posts per page).current
: Thecurrent
parameter specifies the current page number. Here, we use themax()
function, which plays an important role. Let’s see why.
Why Use the max()
Function?
'current' => max( 1, get_query_var( 'paged', 1 ) )
The max()
function in this case returns the largest value between its two arguments. The first argument is 1
, and the second is the result of get_query_var( 'paged', 1 )
, which fetches the current page number.
- If the
paged
parameter is set (e.g., the user is on page 2 or 3), the function returns the page number. - If the
paged
parameter is not present (for example, the user is on the first page where pagination is not needed), it defaults to1
.
The max()
function ensures that the current page number is at least 1
. This is crucial to prevent the pagination from attempting to display invalid pages (such as a negative or zero page number).
In other words, max( 1, get_query_var( 'paged', 1 ) )
ensures that the current page is always valid, especially on the first page.
Final Code
$query = new WP_Query([ 'posts_per_page' => 5, 'paged' => get_query_var( 'paged', 1 ), ]); if ( $query->have_posts() ) { while ( $query->have_posts() ) { $query->the_post(); // Output the post (e.g., the_title(), the_content(), etc.) } // Prints pagination links. echo paginate_links([ 'total' => $query->max_num_pages, 'current' => max( 1, get_query_var( 'paged', 1 ) ), ]); } else { // No posts found. } wp_reset_postdata();
Remember to place the pagination code outside the post loop but still within the PHP tags. This ensures that the pagination displays correctly after all posts have been processed.
Additional Resources
For more detailed information and examples, you can refer to the WordPress Codex on Pagination.
Conclusion
Implementing pagination in WordPress using WP_Query
is straightforward and enhances content accessibility. By using the paged
parameter, you can easily control the display of posts across multiple pages, improving navigation for your visitors. Also, remember the importance of functions like max()
to ensure proper page number handling in your pagination logic.
With this approach, you now have a solid understanding of how pagination works and how to customize it for your WP_Query
. Happy coding!