WordPress Post Navigation Redux (New Tags!)

For years WordPress post navigation has been possible thanks to a flexible set of five functions, including posts_nav_link(), next_post_link() and next_posts_link(). These navigational functions continue to work great in many WordPress themes, but there are newer, even more flexible functions available to theme developers. Introduced in WordPress 4, these new navigation functions can make it easier than ever to display nav links for your WordPress-powered posts.

In this DigWP article, we dig into each of these new navigational tags and check out some examples and techniques to enhance your theme-building skills.

Incredibly, WordPress currently provides 18 nav functions that developers can use to enable post and page navigation. This gives us great flexibility, but the functions are very similar in both naming convention and functionality, and so the myriad choices can be confusing. This post aims to put things into perspective so you can choose the right tool for the job.

Overview

As with the original set of post-navigation functions, this latest set uses a symmetrical naming convention. Here is a quick overview to put all of the WordPress nav tags into perspective¹.

The Newer Navigation Functions

So for this article, here are the newer post-navigation functions that we’ll be exploring (everything in the right column of the previous table):

• Single Posts: get_the_post_navigation + the_post_navigation
• Sets of Posts: get_the_posts_navigation + the_posts_navigation
• Post Pagination: get_the_posts_pagination + the_posts_pagination

For complete coverage of the older post-nav functions, check out The Definitive Guide to WordPress Post Navigation. Also check out Optimizing WordPress Post Navigation for even more post-nav action. Now let’s dig into the new functions..

↑ Single Post Navigation

get_the_post_navigation(), the_post_navigation()

This set of tags can be used to return and display navigation links for next and previous posts, when applicable. Specifically either of these tags may be used when displaying single posts, in order to enable the user to navigate to the next single post or previous single post.

This function returns nav links:

get_the_post_navigation()

And this function displays nav links:

the_post_navigation()

Both functions accept the same optional set of parameters via $args array:

Here is a copy/paste array loaded with the default parameter values:

$args = array(
	'prev_text'          => '%title',
	'next_text'          => '%title',
	'in_same_term'       => false,
	'taxonomy'           => 'category',
	'excluded_terms'     => array(),
	'screen_reader_text' => 'Post navigation'
);

Examples

Display the default navigation links for single posts:

<?php the_post_navigation(); ?>

Display a customized set of single-post nav links:

<?php $args = array(
	'prev_text'          => 'Previous post: %title',
	'next_text'          => 'Next post: %title',
	'in_same_term'       => true,
	'taxonomy'           => 'category',
	'excluded_terms'     => array(1,2,3),
	'screen_reader_text' => 'Post navigation'
);
the_post_navigation($args); ?>

In this example, we display a set of nav links that have customized anchor text and are limited to posts in the same category, excluding categories 1, 2, and 3.

↑ Set of Posts Navigation

get_the_posts_navigation(), the_posts_navigation()

This set of tags can be used to return and display navigation links for next and previous sets of posts, when applicable. Specifically either of these tags may be used to enable the user to navigate between sets of posts, such as those displayed on the home page, front page, archive views, category views, tag views, etc.

This function returns nav links:

get_the_posts_navigation()

And this function displays nav links:

the_posts_navigation()

Both functions accept the same optional set of parameters via $args array:

Here is a copy/paste array loaded with the default parameter values:

$args = array(
	'prev_text'          => 'Older posts',
	'next_text'          => 'Newer posts',
	'screen_reader_text' => 'Post navigation'
);

Examples

Display the default navigation links for current set of posts:

<?php the_posts_navigation(); ?>

Display a customized set of nav links for current set of posts:

<?php $args = array(
	'prev_text'          => 'Previous posts',
	'next_text'          => 'Next posts',
	'screen_reader_text' => 'Post navigation'
);
the_posts_navigation($args); ?>

In this example, we display a set of nav links that have customized anchor text for both previous and next posts.

↑ Post Pagination

get_the_posts_pagination(), the_posts_pagination()

This set of tags can be used to return and display a set of paginated navigation links for next and previous sets of posts, when applicable. Specifically either of these tags may be used to enable the user to navigate between sets of posts, such as those displayed on the home page, front page, archive views, category views, tag views, etc.

These tags generate numerical nav links similar to the following:

« Prev 1 … 3 4 5 6 7 … 9 Next »

This function returns nav links:

get_the_posts_pagination()

And this function displays nav links:

the_posts_pagination()

Both functions accept the same optional set of parameters via $args array:

Here is a copy/paste array loaded with the default parameter values:

$args = array(
	'base'               => '%_%',
	'format'             => '?paged=%#%',
	'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'  => ''
);

Examples

Display the default pagination links for current set of posts:

<?php the_posts_pagination(); ?>

Display a customized set of pagination links for current set of posts:

<?php $args = array(
	'format'    => 'page/%#%/', 
	'prev_text' => '← Older', 
	'next_text' => 'Newer →'
);
the_posts_pagination($args); ?>

In this example, we display a set of pagination links that have a customized link format for permalinks, and also customize the anchor text for both the previous and next post links. You can see this particular configuration implemented at my found-images site, eChunks.com.

References

Visit WordPress.org to learn more about the various navigation functions covered in this article.

• get_the_post_navigation()
• the_post_navigation()
• get_the_posts_navigation()
• the_posts_navigation()
• get_the_posts_pagination()
• the_posts_pagination()

Also check out my post over at WP-Mix to customize post-navigation links with title attributes »