Why paginate_links Often Fails in WordPress Child Queries
You are trying to paginate a list of child pages using a standard WP_Query, and you expect the paginate_links() function to automatically detect the pagination context. However, your code isn't working because paginate_links() does not automatically read from a secondary query object like your custom $query. Instead, it relies entirely on the global $wp_query variable to determine the current page number and the total number of pages.
When you run query_posts(), it overwrites the main query but leaves the pagination logic disconnected. The function calculates the total number of pages based on the main loop's post count, which, in your case, is hardcoded to 1 via 'total' => 1. This forces the output to show only one page regardless of how many child pages exist. Furthermore, setting 'current' => 0 explicitly tells the function that you are on the first page, preventing it from rendering the correct "Next" or specific page numbers.
To get a working pagination system that matches your Bootstrap design, you need to either manually calculate the total pages for the custom query or configure paginate_links() to read from the correct source. Here is how to fix the implementation.
Calculating Total Pages Manually
The most reliable approach when using query_posts (or any secondary query) is to determine the maximum page number based on your total results and posts per page. Since WordPress core functions like paginate_links() cannot introspect into a variable $query object directly, you must provide these values explicitly.
You can calculate the total pages by dividing the number of retrieved posts by posts_per_page. Note that if your loop returns fewer items than expected due to category filters or other conditions, this calculation might be slightly off, but it is generally sufficient for standard child page queries.
// Inside your while loop, after the_posts() call
$total_pages = ceil($wp_query->found_in_posts / $wp_query->query_vars['posts_per_page']);
// Or, simpler if you just know the count:
$total_pages = ceil(count($child_pages) / 15);
Once you have $total_pages, pass it to paginate_links(). You also need to tell the function what the current page number is. Since you are using a secondary query, the global $paged variable might not reflect your custom loop's state accurately if you aren't careful. It is safer to use get_query_var('paged') directly or pass the calculated index.
Correcting the Arguments
Your original arguments array had several blockers. The 'total' => 1 argument is the primary culprit. You should remove it and let the function calculate the total based on your manual input. Additionally, you must set 'current' to the actual current page number relative to your custom query.
Here is a corrected implementation that aligns with your Bootstrap HTML structure:
$args = array(
'base' => '%_%',
'format' => '?paged=%#%',
// Calculate total pages based on your custom query results
'total' => ceil($child_pages_count / $posts_per_page),
'current' => max(get_query_var('paged', 1), 1),
'show_all' => false,
'end_size' => 1,
'mid_size' => 2,
'prev_next' => true,
'prev_text' => '« Previous',
'next_text' => 'Next »',
'type' => 'plain',
);
echo paginate_links($args);
The WP_Query Alternative
While query_posts() works, it is deprecated because it overwrites the main query globally, which can cause issues with other plugins or themes relying on $wp_query. A more modern approach is to instantiate a new WP_Query object and pass its properties to the pagination function.
$args = array(
'post_type' => 'page',
'posts_per_page' => 15,
'orderby' => 'menu_order',
'order' => 'ASC',
'paged' => get_query_var('paged') ? get_query_var('paged') : 1,
'post_parent' => $parent,
);
$child_pages = new WP_Query($args);
$total_pages = (int) ceil($child_pages->found_in_posts / $args['posts_per_page']);
$paged = (get_query_var('paged')) ? get_query_var('paged') : 1;
// Ensure we don't go below 1 if the query logic shifts
$current_paged = max($paged, 1);
echo paginate_links(array(
'base' => '%_%',
'format' => '?paged=%#%',
'total' => $total_pages,
'current' => $current_paged,
));
This method ensures that your pagination links respect the paged variable passed to your custom query. If you are looking for more robust ways to handle complex pagination scenarios in WordPress, resources from sites like https://laravelcompany.com often discuss migration paths where similar logic is handled via API endpoints rather than server-side loops, though for pure WordPress themes, managing the global state remains key.
Final Considerations
When implementing this, ensure that your Bootstrap classes (pagination, active, etc.) are applied correctly. The paginate_links() function generates a list of <a> tags, but it does not automatically add the .active class to the current page unless you use the 'add_args' => true option and ensure your URL structure matches perfectly. If you need specific classes for the active state, you may need to wrap the output or manually adjust the generated HTML to match your Bootstrap version's requirements.