WordPress Post Navigation Redux (New Tags!)

WordPress Post Navigation Redux (New Tags!) For years WordPress post navigation has been possible thanks to a flexible

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.

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.

Nav Type Older Functions Newer Functions
Single Posts get_previous_post_link
previous_post_link
get_next_post_link
next_post_link
get_the_post_navigation
the_post_navigation
Sets of Posts
(Archives)
get_previous_posts_link
previous_posts_link
get_next_posts_link
next_posts_link
get_posts_nav_link
posts_nav_link
get_the_posts_navigation
the_posts_navigation
Post Pagination paginate_links
wp_link_pages
get_the_posts_pagination
the_posts_pagination

Note: all of these tags continue work great with WordPress. The “older” and “newer” distinction is to help differentiate the newer nav functions.

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):

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:

Parameter Description Default Value
prev_text (string) Anchor text for previous post link %title
next_text (string) Anchor text for next post link %title
in_same_term (bool) Whether link should be in a same taxonomy term false
taxonomy (string) Taxonomy, if $in_same_term is true category
excluded_terms (array|string) Array or comma-separated list of excluded term IDs array()
screen_reader_text (string) Screen reader text for nav element Post navigation

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:

Parameter Description Default Value
prev_text (string) Anchor text for previous posts link Older posts
next_text (string) Anchor text for next posts link Newer posts
screen_reader_text (string) Screen reader text for nav element Posts navigation

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:

Parameter Description Default Value
base (string) Base of the paginated URL %_%
format (string) Format for pagination structure ?page=%#%
total (int) The total amount of pages Value of WP_Query’s max_num_pages or 1
current (int) The current page number Value of the paged query variable or 1
show_all (bool) Whether to show all pages false
end_size (int) How many numbers on either the start and the end list edges 1
mid_size (int) How many numbers to either side of the current pages 2
prev_next (bool) Whether to include the previous and next links in the list true
prev_text (string) The previous page text « Previous
next_text (string) The next page text Next »
type (string) Controls format of the returned value, either plain, array or list plain
add_args (array) An array of custom query args false
add_fragment (string) Custom string appended to each link none
before_page_number (string) Custom string prepended to each page number none
after_page_number (string) Custom string appended to each page number none
screen_reader_text (string) Screen reader text for navigation element Posts navigation

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' => '&larr; Older', 
	'next_text' => 'Newer &rarr;'
);
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 nav functions covered in this article.



Source: WordPress Post Navigation Redux (New Tags!)

Leave a Comment