1. paginate_links()
  2. Example of custom pagination

Pagination for Custom Loops

There are different ways to create a pagination for WordPress posts in a loop:

  • Using next_posts_link() and previous_posts_links() functions
  • Using paginate_links() or get_the_posts_pagination() that allows to display numeric pagination.
  • In old times we also used plugins for that purpose, the most popular was WP-Pagenavi.

In this tutorial my goal is to show you how to create any kind of custom paginations for almost anything. For example did you know that do display page numbers in Appearance > Menus is also used paginate_links() function?

custom pagination in WordPress nav menus

As I mentioned above this functions can be used to paginate almost anything. In order to do so, we need to pass some specific parameters to the functions.

Let me break down all function parameters into two groups:

For stylingFor custom pagination
show_all, mid_size, end_size, prev_next, prev_text, next_text, before_page_number, after_page_number, typetotal, current, base, format

All parameters detailed description you can find in official WordPress documentation, but right now I am going to dive deep into parameters of the second group.

  • total – total number of pages in pagination,
  • current – current page number,
  • base – it is how URL of a single navigation page looks like in format  http://test-site/all_posts.php%_%, symbols %_% are going to be replaced with the value of format parameter, for example to /page/1 or ?pg=1. By default for archive pages WordPress uses the value of get_pagenum_link() function with %_% on the end.
  • format – that’s the parameter which contains the actual page number in format ?page=%#%, where %#% is the current page number.

Example of Custom WordPress Query Pagination

Right now let’s create a pagination for any custom WordPress query. We can use WP_Query class to display posts or Network_Query which works like WP_Query but for all the posts in Multisite Network. But please note that in order to use the second class, my plugin should be installed on your website.

I decided to show you a pagination example based on a page template we created in a tutorial about global multisite search. 

<?php
/*
 * Template name: Global Search with Pagination
 */
get_header();

// could be almost anything but I don't recommend to use 'page' or 'paged'
$query_arg = 'current_page';
// URL of your search page
$page_url = get_permalink(); // or get_pagenum_link() or something custom

$current_page = ( isset( $_GET[ $query_arg ] ) && $_GET[ $query_arg ] ) ? absint( $_GET[ $query_arg ] ) : 1;

$args = array(
	's' => 'wordcamp london', // the search query is here
	'posts_per_page' => 10, // decide how much posts per page should be displayed
	'paged' => $current_page
);

// run the custom query
$query = new Network_Query( $args );

if( $query->have_posts() ) :

	while( $query->have_posts() ) : $query->the_post();

		?><h2><?php echo $query->post->post_title ?></h2><?php

	endwhile;

	if( $query->max_num_pages > 1 ) {
		echo paginate_links(
			array(
				'total' => $query->max_num_pages,
				'current' => $current_page,
				'base' => $page_url . '%_%',
				'format' => '?' . $query_arg . '=%#%'
			)
		);
	}
	
endif;

get_footer();

# Multisite, WordPress

Misha Rudrastyh

Misha Rudrastyh

Hey guys and welcome to my website. For more than 10 years I've been doing my best to share with you some superb WordPress guides and tips for free.

Need some developer help? Contact me

Follow me on X