WPBeginner» Blog» Themes» How to Add Numeric Pagination in Your WordPress Theme

How to Add Numeric Pagination in Your WordPress Theme

Last updated on May 1st, 2013 by Editorial Staff

Special WordPress Hosting offer for WPBeginner Readers

How to Add Numeric Pagination in Your WordPress Theme

One of our readers recently asked us how do we add numeric pagination on the WPBeginner blog page. Default WordPress themes and many other themes display pagination links by adding Older posts and Newer Posts links at the bottom of your WordPress archive pages. However, there are many WordPress sites that uses numeric pagination, like WPBeginner. From our experience, numeric pagination is more user friendly, attractive, and SEO friendly. Most advanced WordPress theme frameworks like Genesis comes with a built-in functionality for adding numeric pagination. In this article we will show you how to add numeric pagination in your WordPress theme. The goal is to replace the default Older and Newer pagination links at the bottom of archive pages with easy to navigate page numbers.

Difference between default WordPress navigation and Numeric Pagination

There are two methods to adding numeric pagination in your WordPress theme. The first method is manually adding numeric pagination without relying on a third party plugin. Since this article is in the theme category and intended for new theme designers, we will show the manual method first. The second method is to use an existing third party plugin to add numeric pagination. We would recommend that method for all of our DIY users.

Manually adding Numeric Pagination in Your WordPress Themes

First we will show you how to manually add numeric pagination in your WordPress themes. This will benefit our advanced users, and users who are learning theme development, or want to do this without relying on a third party plugin. Lets get started by adding the following code in your theme’s functions.php file.

Note: This code is derived from Genesis Framework which we use on our site. If you are using Genesis, then you don’t need this code or the plugin.


function wpbeginner_numeric_posts_nav() {

	if( is_singular() )
		return;

	global $wp_query;

	/** Stop execution if there's only 1 page */
	if( $wp_query->max_num_pages <= 1 )
		return;

	$paged = get_query_var( 'paged' ) ? absint( get_query_var( 'paged' ) ) : 1;
	$max   = intval( $wp_query->max_num_pages );

	/**	Add current page to the array */
	if ( $paged >= 1 )
		$links[] = $paged;

	/**	Add the pages around the current page to the array */
	if ( $paged >= 3 ) {
		$links[] = $paged - 1;
		$links[] = $paged - 2;
	}

	if ( ( $paged + 2 ) <= $max ) {
		$links[] = $paged + 2;
		$links[] = $paged + 1;
	}

	echo '<div class="navigation"><ul>' . "\n";

	/**	Previous Post Link */
	if ( get_previous_posts_link() )
		printf( '<li>%s</li>' . "\n", get_previous_posts_link() );

	/**	Link to first page, plus ellipses if necessary */
	if ( ! in_array( 1, $links ) ) {
		$class = 1 == $paged ? ' class="active"' : '';

		printf( '<li%s><a href="%s">%s</a></li>' . "\n", $class, esc_url( get_pagenum_link( 1 ) ), '1' );

		if ( ! in_array( 2, $links ) )
			echo '<li>…</li>';
	}

	/**	Link to current page, plus 2 pages in either direction if necessary */
	sort( $links );
	foreach ( (array) $links as $link ) {
		$class = $paged == $link ? ' class="active"' : '';
		printf( '<li%s><a href="%s">%s</a></li>' . "\n", $class, esc_url( get_pagenum_link( $link ) ), $link );
	}

	/**	Link to last page, plus ellipses if necessary */
	if ( ! in_array( $max, $links ) ) {
		if ( ! in_array( $max - 1, $links ) )
			echo '<li>…</li>' . "\n";

		$class = $paged == $max ? ' class="active"' : '';
		printf( '<li%s><a href="%s">%s</a></li>' . "\n", $class, esc_url( get_pagenum_link( $max ) ), $max );
	}

	/**	Next Post Link */
	if ( get_next_posts_link() )
		printf( '<li>%s</li>' . "\n", get_next_posts_link() );

	echo '</ul></div>' . "\n";

}

At WPBeginner, we use this same code for numeric pagination on our archive pages (for example our blog, or WordPress tutorials category page). What this code does is that it retrieves the number of pages and prepares a bulleted list of numbered links. To add this in your templates, you will have to add the following template tag in your theme’s index.php, archive.php, category.php, and any other archive page template.

	<?php wpbeginner_numeric_posts_nav(); ?>

Now that we have got our list of numbered pages, we need to style this list. We want to make the list appear in-line block where the active page is highlighted with a different background color. To accomplish that, lets go ahead and add the following in your theme’s style.css file:

.navigation li a,
.navigation li a:hover,
.navigation li.active a,
.navigation li.disabled {
	color: #fff;
	text-decoration:none;
}

.navigation li {
	display: inline;
}

.navigation li a,
.navigation li a:hover,
.navigation li.active a,
.navigation li.disabled {
	background-color: #6FB7E9;
	border-radius: 3px;
	cursor: pointer;
	padding: 12px;
	padding: 0.75rem;
}

.navigation li a:hover,
.navigation li.active a {
	background-color: #3C8DC5;
}

There you have it. We have a list of numeric pagination in our theme that looks great.

Manually adding numeric pagination to WordPress themes without a plugin

Adding Numeric Pagination in WordPress using WP-PageNavi

Now let’s take a look at how to add numeric pagination in your WordPress theme by using an existing plugin called WP-PageNavi. First thing you need to do is install and activate WP-PageNavi plugin. After activating the plugin go to Settings » PageNavi to configure the plugin settings.

Configuring WP-PageNavi settings

On the plugin settings page you can replace the default text and numeric pagination settings with your own if you want. However, the default settings should work for most websites.

In the next step, you need to add a template tag in your WordPress Theme. Go to your theme folder and find the lines for older and newer pagination in your archive page templates: index.php, archive.php and any other archive template files. Add the following template tag to replace the old previous_posts_link and next_posts_link tags.

<?php wp_pagenavi(); ?>

Once you have added the wp_pagenavi snippet, this is how the numeric pagination would look like:

Default view of wp-pagenavi's numeric pagination

If you want to change how the colors and style of numeric pagination in wp-pagenavi looks, then you would need to go to Settings » PageNavi. Uncheck the option to use Use pagenavi-css.css and save changes. Now go to Plugins » Editor. From Select plugin to edit drop down menu, select WP-PageNavi and click on the Select button. The editor will load plugin files in the right hand sidebar. Click on pagenavi-css.css to open it in editor and then copy the contents of the file.

Copy the contents of pagenavi-css file

Next, you need to go to Appearance » Editor and paste the contents of pagenavi-css.css into your theme’s style.css file. Now you can modify the color scheme and styling from here. The reason why we copied the contents of plugin’s css to theme’s stylesheet is to prevent loss of style changes should you update the plugin. Here is a slightly modified version of numeric pagination, feel free to use and modify it in your theme.


.wp-pagenavi {
	clear: both;
}

.wp-pagenavi a, .wp-pagenavi span {
	color: #FFF;
	text-decoration: none;
	background-color:#6FB7E9; 
	border: 1px solid #B2D1E5;
	padding: 5px 5px;
	margin: 2px;
}

.wp-pagenavi a:hover, .wp-pagenavi span.current {
	border-color: #E9F2F9;
	background-color:#6FB7E9;
}

.wp-pagenavi span.current {
	font-weight: bold;
	background-color:#3C8DC5;
}

Here is how it would look like:

Customized PageNavi CSS

As always you should experiment with CSS. The goal should be to match the numeric pagination with look and feel of your website’s colors, so that it blends in nicely and does not look like an oddly placed item.

We hope that this article helped you add and display numeric pagination in your WordPress theme. Which method do you prefer to use? Do you like the numeric pagination or do you prefer the built-in previous/next navigation? Let us know in the comments below.