Adding Numbered Pagination in a WordPress Template

If you are looking for a way to add numbered pagination to your WordPress template instead of the default “Next Posts” and “Previous Posts,” you can easily do so using the plugin that most of you probably know, called WP-PageNavi.

Personally, I prefer adding pagination manually to the templates I build, avoiding the use of plugins. This not only helps to maintain the speed of these templates but also saves unnecessary use of CSS and JavaScript files.

So, there’s a function that I’ve noticed not many are familiar with, called paginate_links, added to WordPress in version 2.1. This function allows you to create numbered pagination for any query in your WordPress template.

By default, the function comes with the following settings:

<?php $args = array(
 'base'               => '%_%',
 'format'             => '?page=%#%', // the '%#%' will be replaced with the page number
 'total'              => 1,
 'current'            => 0,
 'show_all'           => False,
 'end_size'           => 1,
 'mid_size'           => 2,
 'prev_next'          => True,
 'prev_text'          => __('« Previous'),
 'next_text'          => __('Next »'),
 'type'               => 'plain',
 'add_args'           => False,
 'add_fragment'       => '',
 'before_page_number' => '',
 'after_page_number'  => ''
); ?>

Not going into detail about these settings, but take a look at the WordPress Codex to learn about all the parameters of the paginate_links() function.

Anyway, here’s a brief guide on how to add numbered pagination to WordPress that looks exactly like the pagination on this blog.

Adding Pagination to a WordPress Template

Add the following code to the functions.php file in your child theme (or any file you deem appropriate in your template):

/**
 * Pagination for archive, taxonomy, category, tag and search results pages
 *
 * @global $wp_query http://codex.wordpress.org/Class_Reference/WP_Query
 * @return Prints the HTML for the pagination if a template is $paged
 */
function sv_pagination() {
	global $wp_query;

	$next_arrow = is_rtl() ? '>' : '<';
	$prev_arrow = is_rtl() ? '<' : '>';

	$total      = $wp_query->max_num_pages;

	$big = 999999999; // This needs to be an unlikely integer

	// For more options and info view the docs for paginate_links()
	// http://codex.wordpress.org/Function_Reference/paginate_links
	$paginate_links = paginate_links( array(
		'base'        => str_replace( $big, '%#%', esc_url( get_pagenum_link($big) ) ),
		'current'     => max( 1, get_query_var('paged') ),
		'total'       => $total,
		'show_all'    => true,
		'prev_text'	  => $prev_arrow,
		'next_text'	  => $next_arrow
	) );

	// Display the pagination if more than one page is found
	if ( $paginate_links ) {
		echo '<div class="pagination">';
		echo $paginate_links;
		echo '</div>';
	}
}

We’ve set a number of basic parameters for the paginate_links function, and the truth is I haven’t gone through all of them. However, it’s important to note – if you want to make the pagination accessible (and it’s recommended that you do),

Add the following variable at the beginning of the paginate_links function:

$translated = __( 'Page', 'mytextdomain' );

In addition, add the following parameter to the paginate_links array in the above code:

'before_page_number' => '<span class="accessible-txt">'.$translated.' </span>'

I assume you’d want to hide the accessible-txt class in your CSS file…

Pagination Styling

We’ll use Flexbox to make things easier. To style the numbered pagination like this blog, add the following code to your child theme’s style.css file: child theme.

.pagination {
    display: flex;
    -webkit-box-pack: justify;
    -moz-box-pack: justify;
    -ms-flex-pack: justify;
    -webkit-justify-content: space-between;
    justify-content: space-between;
    flex-flow: row wrap;
}

.pagination > * {
    color: #2d2d2d;
    border-radius: 50%;
    text-align: center;
    -webkit-flex-basis: 36px; /* Safari 6.1+ */
    flex-basis: 36px;
    line-height: 36px;
    min-width: 36px;
    margin: 4px 0;
}

.pagination > * {
    color: #2d2d2d;
    border-radius: 50%;
    text-align: center;
    background: #f3f3ef;
}

.pagination > a:hover, span.current {
    background-color: #942762;
    color: #fefefe;

}

Adding Pagination to Your Template

Very simple, to call the pagination function in your template, all you need to do is add the following line to your template wherever you want the pagination to appear. Typically, you would add this code to the index.php, category.php, archive.php, etc. However, if you have a custom page template, add it there.

<?php sv_pagination(); ?>

Of course, if you’re using a page template or a file that already has the default WordPress pagination, replace it with this code.

Custom Query?

If you are using a custom loop using WP_Query, the code won’t work unless you have set your query in the $wp_query variable (avoid doing this). To fix this when creating a custom loop, it usually looks like this:

$sv_query = new WP_Query( $args );

In this way, we can modify the pagination function to check if you used this variable to create the loop and adjust the $total variable accordingly (update the first code snippet in this post).

global $wp_query, $sv_query;
if ( $sv_query ) {
    $total = $sv_query->max_num_pages;
} 
else {
    $total = $wp_query->max_num_pages;
}

הלולאה המותאמת שלכם אמורה בעיקרון להראות בסגנון הבא:

<?php
    $paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1;

    $args     = array(
        'post_type'      => 'post', // You can add a custom post type if you like
        'posts_per_page' => 6,
        'paged'          => $paged
    );
    $sv_query = new WP_Query( $args );

    if ( $sv_query->have_posts() ) : while ( $sv_query->have_posts() ) : $sv_query->the_post();

        //*** Post content goes here 

    endwhile;
        sv_pagination();
        wp_reset_postdata();
    else :

        //*** If no posts found message goes here 

    endif;
?>

Please notice that in line 17 (at the end of the loop) we used the wp_reset_postdata() function to reset the global variable $post after using the new loop created by WP_Query.

Summary

Using numbered pagination provides a simple and clear way for users to navigate your blog. Through it, users can easily know how many pages and posts exist on your site, providing a more user-friendly experience.

By adding a few lines of PHP and CSS, you can easily add a beautiful pagination to your WordPress blog. More on pagination and the rel="next" and rel="prev" tags in the next post.

Is it working for you? Any ideas for improvement? Share your thoughts in the comments so we can all learn… 🙂