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.
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):
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:
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:
Examples
Display the default navigation links for single posts:
Display a customized set of single-post nav links:
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:
Examples
Display the default navigation links for current set of posts:
Display a customized set of nav links for current set of posts:
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:
Examples
Display the default pagination links for current set of posts:
Display a customized set of pagination links for current set of posts:
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.
get_the_post_navigation()
the_post_navigation()
get_the_posts_navigation()
the_posts_navigation()
get_the_posts_pagination()
the_posts_pagination()
