WordPress at a glance

get_the_post_navigation() WP 4.1.0

Gets the navigation links (HTML) to the next and previous posts. Uses on a single post page: is_singular().

You can use it for example, for navigation between attachments (attached images).

Up to version 4.1. to output links to the previous/next post, you had to use the get_next_post_link() and get_previous_post_link() functions. This function is a wrapper for these functions.

To immediately display the result on the screen, use the_post_navigation().

Is the basis for: the_post_navigation()

No Hooks.


String. HTML Markup for post links.


get_the_post_navigation( $args );

Default empty array.

  • $prev_text (string)
    Anchor text to display in the previous post link.
    Default: '%title'

  • $next_text (string)
    Anchor text to display in the next post link.
    Default: '%title'

  • $in_same_term (true/false)
    Whether link should be in a same taxonomy term.
    Default: false

  • $excluded_terms (array/string)
    Array or comma-separated list of excluded term IDs.
    Default: ''

  • $taxonomy (string)
    Taxonomy, if $in_same_term is true.
    Default: 'category'

  • $screen_reader_text (string)
    Screen reader text for nav element.
    Default: 'Post navigation'

Default: post navigation arguments


#1 Navigation links between posts

Let's output links to the next and previous entries (posts) on a separate page of is_single() type.

// next/prev. post
$post_nav = get_the_post_navigation( array(
	'prev_text' => '<span class="meta-nav" aria-hidden="true">Backward</span> ' .
		'<span class="screen-reader-text">Previous entry</span> ' .
		'<span class="post-title">%title</span>',
	'next_text' => '<span class="meta-nav" aria-hidden="true">Further</span> ' .
		'<span class="screen-reader-text">Next entry</span> ' .
		'<span class="post-title">%title</span>',
) );

echo $post_nav;

As a result, we get such HTML code:

<nav class="navigation post-navigation" role="navigation">
	<h2 class="screen-reader-text">Posts navigation</h2>
	<div class="nav-links">
		<div class="nav-previous">
			<a href="//wptest.ru/post8/" rel="prev">
				<span class="meta-nav" aria-hidden="true">Backward</span>
				<span class="screen-reader-text">Previous entry</span>
				<span class="post-title">Some Post Title</span>
		<div class="nav-next">
			<a href="//wptest.ru/post10/" rel="next">
				<span class="meta-nav" aria-hidden="true">Further</span>
				<span class="screen-reader-text">Next entry</span>
				<span class="post-title">Hello World!</span>


Since 4.1.0 Introduced.
Since 4.4.0 Introduced the in_same_term, excluded_terms, and taxonomy arguments.

Code of get the post navigation: wp-includes/link-template.php WP 5.2.4

function get_the_post_navigation( $args = array() ) {
	$args = wp_parse_args(
			'prev_text'          => '%title',
			'next_text'          => '%title',
			'in_same_term'       => false,
			'excluded_terms'     => '',
			'taxonomy'           => 'category',
			'screen_reader_text' => __( 'Post navigation' ),

	$navigation = '';

	$previous = get_previous_post_link(
		'<div class="nav-previous">%link</div>',

	$next = get_next_post_link(
		'<div class="nav-next">%link</div>',

	// Only add markup if there's somewhere to navigate to.
	if ( $previous || $next ) {
		$navigation = _navigation_markup( $previous . $next, 'post-navigation', $args['screen_reader_text'] );

	return $navigation;

Related Functions

From tag: adjacent links (related links)

More from tag: Navigation pagination

More from category: Navigation

No comments
    Hello, !     Log In . Register