How to Use WordPress Built-in Pagination with WP_Query

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: The total 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 the posts_per_page setting (for example, 5 posts per page).
• current: The current parameter specifies the current page number. Here, we use the max() 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 to 1.

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!