Pagination with custom queries in Wordpress - Deep Dive

Overview - Pagination with custom queries

What is it?

Pagination with custom queries in WordPress means splitting a list of posts or items into multiple pages when you use your own special search or filter instead of the usual blog posts. It helps visitors see a few items at a time instead of all at once, making the site faster and easier to use. You create a custom query to get exactly the posts you want, then add pagination to let users move between pages of results.

Why it matters

Without pagination, a page with many posts or items would load very slowly and be hard to read. Visitors might leave because they have to scroll forever. Pagination with custom queries solves this by showing only a small set of results per page and letting users navigate easily. This improves user experience and site performance, especially when you want to show filtered or special content that the default WordPress query doesn't handle.

Where it fits

Before learning this, you should understand basic WordPress themes, the Loop, and how WP_Query works for custom queries. After this, you can learn about AJAX pagination for smoother page changes or how to combine pagination with advanced filters and sorting.

Mental Model

Core Idea

Pagination with custom queries divides a large set of filtered posts into manageable pages by controlling which posts show on each page and providing navigation links.

Think of it like...

It's like a book index that shows only a few entries per page and lets you flip to the next or previous page to find more entries, instead of dumping the whole index at once.

┌───────────────┐
│ Custom Query  │
│ (filtered)    │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Pagination    │
│ (page 1, 2...)│
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Display Posts │
│ for current   │
│ page          │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding WordPress Queries

Concept: Learn what WordPress queries are and how they fetch posts.

WordPress uses a query to decide which posts to show on a page. The main query runs automatically and shows posts based on the URL. You can create a custom query using WP_Query to get posts with specific filters like category, tag, or custom fields.

Result

You can fetch a list of posts that match your criteria instead of the default posts.

Understanding queries is key because pagination controls which part of this list you show at a time.

2

Foundation

What is Pagination in WordPress?

Concept: Pagination splits content into pages and provides navigation links.

Pagination means showing a limited number of posts per page and letting users click links to see more posts on other pages. WordPress has built-in functions like paginate_links() to create these navigation links.

Result

Users see a few posts per page and can click to go to next or previous pages.

Pagination improves user experience by avoiding long pages and speeding up load times.

3

Intermediate

Adding Pagination to Custom WP_Query

🤔Before reading on: do you think you can use the same pagination functions for custom queries as for the main query? Commit to your answer.

Concept: Learn how to paginate results from a custom WP_Query by setting the right parameters and using pagination functions.

When you create a custom WP_Query, you must tell it which page of results to show using the 'paged' parameter. Then, use paginate_links() with the total number of pages from your query to create navigation links. Example: $paged = get_query_var('paged') ? get_query_var('paged') : 1; $args = ['post_type' => 'post', 'posts_per_page' => 5, 'paged' => $paged]; $query = new WP_Query($args); while ($query->have_posts()) { $query->the_post(); /* show post */ } echo paginate_links(['total' => $query->max_num_pages]);

Result

The page shows 5 posts per page with links to navigate between pages of the custom query.

Knowing to pass the 'paged' parameter and use max_num_pages is crucial for correct pagination with custom queries.

4

Intermediate

Handling Pagination URLs Correctly

🤔Before reading on: do you think pagination URLs always use 'paged' query variable? Commit to your answer.

Concept: Understand how WordPress builds pagination URLs and how to make them work with custom queries and permalinks.

Pagination URLs depend on your permalink settings. For pretty permalinks, URLs look like /page/2/. For default permalinks, they use ?paged=2. Use get_query_var('paged') to get the current page number. Also, when using custom queries on custom templates or archives, ensure the pagination base and format in paginate_links() match your URL structure.

Result

Pagination links work correctly and lead to the right pages without 404 errors.

Correct URL handling prevents broken links and ensures users can navigate pages smoothly.

5

Intermediate

Resetting Post Data After Custom Queries

Concept: Learn why and how to reset global post data after running a custom query.

After using a custom WP_Query loop, call wp_reset_postdata() to restore the global $post variable to the main query. This prevents conflicts with other parts of the page that rely on the main query's data.

Result

Other template parts work correctly after your custom query and pagination.

Resetting post data avoids subtle bugs where wrong post info shows after custom queries.

6

Advanced

Custom Pagination for Complex Queries

🤔Before reading on: do you think paginate_links() works automatically with any custom query? Commit to your answer.

Concept: Explore how to build pagination when your query uses complex filters or joins that WP_Query can't handle directly.

For very custom queries (e.g., raw SQL or multiple post types combined), WP_Query pagination helpers may not work. You must calculate total pages manually and build pagination links yourself. Use get_query_var('paged') for current page and build URLs with add_query_arg() or custom rewrite rules. Then slice your results array to show only the current page's items.

Result

You can paginate any custom data set, even outside WP_Query, with correct navigation.

Knowing how to manually paginate gives flexibility beyond WP_Query limits.

7

Expert

Optimizing Pagination Performance

🤔Before reading on: do you think loading all posts then slicing is efficient for pagination? Commit to your answer.

Concept: Learn how to optimize custom query pagination to avoid performance issues on large datasets.

Loading all posts and then slicing in PHP is slow and memory-heavy. Instead, use WP_Query's 'paged' and 'posts_per_page' to limit database results. For very large sites, consider caching query results or using transient caching for pagination links. Also, avoid expensive meta queries or joins in pagination queries to keep page loads fast.

Result

Pagination runs smoothly even on sites with thousands of posts.

Efficient pagination prevents slow pages and server overload, improving user experience and scalability.

Under the Hood

WordPress pagination works by limiting the number of posts fetched from the database using SQL LIMIT and OFFSET clauses. The 'paged' parameter tells WP_Query which set of posts to retrieve. Pagination links are generated based on the total number of posts divided by posts per page. When a user clicks a pagination link, the page reloads with a different 'paged' value, fetching the next set of posts.

Why designed this way?

This design keeps page loads fast by only fetching needed posts, not all posts at once. It leverages SQL's built-in LIMIT/OFFSET for efficiency. Using query variables like 'paged' integrates with WordPress's URL routing and permalink system, making pagination seamless and SEO-friendly.

┌───────────────┐
│ User clicks   │
│ pagination   │
│ link (page 2) │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ WordPress     │
│ reads 'paged' │
│ query var     │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ WP_Query runs │
│ SQL with      │
│ LIMIT/OFFSET  │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Posts for     │
│ current page  │
│ fetched       │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Pagination    │
│ links built   │
│ with max pages│
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does paginate_links() automatically work with any custom WP_Query? Commit to yes or no.

Common Belief: paginate_links() works out of the box with any custom WP_Query without extra setup.

Reality: paginate_links() needs the total number of pages and current page passed explicitly from your custom query; it doesn't auto-detect them.

Why it matters: Without passing correct parameters, pagination links may be missing or incorrect, confusing users.

Quick: Is it okay to ignore wp_reset_postdata() after a custom query? Commit to yes or no.

Common Belief: You don't need to reset post data after a custom WP_Query loop; WordPress handles it automatically.

Reality: You must call wp_reset_postdata() after custom queries to restore global post variables; otherwise, other template parts may break.

Why it matters: Failing to reset causes wrong post data to show, leading to bugs and confusing content.

Quick: Can you paginate custom queries by loading all posts and slicing in PHP? Commit to yes or no.

Common Belief: Loading all posts and slicing in PHP is fine for pagination.

Reality: This approach is inefficient and slow for large datasets; it's better to limit posts in the database query.

Why it matters: Inefficient pagination causes slow page loads and high server load, hurting user experience.

Quick: Does the 'paged' query variable always come from the URL? Commit to yes or no.

Common Belief: 'paged' is always set and reliable from the URL for pagination.

Reality: 'paged' may be missing or zero on the first page, so you must default it to 1 in your code.

Why it matters: Not handling missing 'paged' causes your query to fail or show wrong posts on page 1.

Expert Zone

1

Pagination links should respect the site's permalink structure and query vars to avoid 404 errors or broken navigation.

2

When stacking multiple custom queries on one page, each needs its own pagination logic and careful management of query vars to avoid conflicts.

3

Caching pagination results can dramatically improve performance but requires careful invalidation when content changes.

When NOT to use

Avoid custom query pagination when the default WordPress main query can be adjusted with pre_get_posts filters for simpler code. For very dynamic or infinite scroll interfaces, consider AJAX-based loading instead of traditional pagination.

Production Patterns

In production, developers often combine custom queries with pagination in archive templates or custom post type listings. They use get_query_var('paged') carefully, reset post data, and style paginate_links() for consistent UI. Advanced sites implement AJAX pagination to load pages without full reloads.

Connections

Database Indexing

Pagination relies on efficient database queries which depend on proper indexing.

Understanding how database indexes speed up LIMIT/OFFSET queries helps optimize pagination performance.

User Interface Design

Pagination is a UI pattern to improve navigation and content consumption.

Knowing UI principles helps design pagination controls that are easy and intuitive for users.

Memory Paging in Operating Systems

Both break large data sets into smaller chunks for efficient access.

Seeing pagination like OS memory paging reveals the importance of loading only needed data to save resources.

Common Pitfalls

#1 Pagination links do not appear or lead to wrong pages.

Wrong approach:

$paged = get_query_var('paged');
$args = ['posts_per_page' => 5, 'paged' => $paged];
$query = new WP_Query($args);
// forgot to check if $paged is empty or zero

echo paginate_links(['total' => $query->max_num_pages]);

Correct approach:

$paged = get_query_var('paged') ? get_query_var('paged') : 1;
$args = ['posts_per_page' => 5, 'paged' => $paged];
$query = new WP_Query($args);
echo paginate_links(['total' => $query->max_num_pages]);

Root cause:

Not defaulting 'paged' to 1 causes the query to fetch wrong posts and pagination links to fail.

#2 After custom query loop, other parts of the page show wrong post data.

Wrong approach:

$query = new WP_Query($args);
while ($query->have_posts()) { $query->the_post(); /* show post */ }
// forgot wp_reset_postdata() here

Correct approach:

$query = new WP_Query($args);
while ($query->have_posts()) { $query->the_post(); /* show post */ }
wp_reset_postdata();

Root cause:

Global $post variable remains changed after custom query, breaking other template code.

#3 Loading all posts then slicing in PHP for pagination.

Wrong approach:

$all_posts = get_posts(['posts_per_page' => -1]);
$page = get_query_var('paged') ?: 1;
$per_page = 5;
$offset = ($page - 1) * $per_page;
$posts_to_show = array_slice($all_posts, $offset, $per_page);

Correct approach:

$paged = get_query_var('paged') ?: 1;
$args = ['posts_per_page' => 5, 'paged' => $paged];
$query = new WP_Query($args);

Root cause:

Fetching all posts wastes memory and slows down page load.

Key Takeaways

Pagination with custom queries lets you show filtered posts in smaller, manageable pages improving site speed and user experience.

Always pass the 'paged' parameter to your WP_Query and default it to 1 to avoid errors on the first page.

Use paginate_links() with the total pages from your query to build navigation links that work with your site's URLs.

Reset post data after custom queries to keep the rest of your page working correctly.

For very complex or large queries, manual pagination and performance optimization are necessary to keep your site fast.