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().

Used By: the_post_navigation()

No Hooks.

Return

String. HTML Markup for post links.

Usage

get_the_post_navigation( $args );
$args(array)

Default empty array.

Default: post navigation arguments

  • 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(int[]|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 the nav element.
    Default: 'Post navigation'

  • aria_label(string)
    ARIA label text for the nav element.
    Default: 'Posts'

  • class(string)
    Custom class for the nav element.
    Default: 'post-navigation'

Examples

0

#1 Navigation links between posts

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

<?php
// 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="//example.com/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>
			</a>
		</div>
		<div class="nav-next">
			<a href="//example.com/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>
			</a>
		</div>
	</div>
</nav>
0

#2 Add title attribute to links

This example shows how to add the attribute <a title="" ...> to every link in the block. The value will contain the title of the post and will be preceded by the word See:: title=`See: POST_TITLE.

add_filter( 'next_post_link', 'add_title_adjacent_post_link', 10, 4 );
add_filter( 'previous_post_link', 'add_title_adjacent_post_link', 10, 4 );

function add_title_adjacent_post_link( $output, $format, $link, $post ){

	$title = esc_attr( 'See: '. $post->post_title );

	return str_replace( '<a', "<a title='$title'", $output );
}

The code must be added just before calling get_the_post_navigation().

Changelog

Since 4.1.0 Introduced.
Since 4.4.0 Introduced the in_same_term, excluded_terms, and taxonomy arguments.
Since 5.3.0 Added the aria_label parameter.
Since 5.5.0 Added the class parameter.

get_the_post_navigation() code WP 6.1.1

wp-includes/link-template.php 
function get_the_post_navigation( $args = array() ) {
	// Make sure the nav element has an aria-label attribute: fallback to the screen reader text.
	if ( ! empty( $args['screen_reader_text'] ) && empty( $args['aria_label'] ) ) {
		$args['aria_label'] = $args['screen_reader_text'];
	}

	$args = wp_parse_args(
		$args,
		array(
			'prev_text'          => '%title',
			'next_text'          => '%title',
			'in_same_term'       => false,
			'excluded_terms'     => '',
			'taxonomy'           => 'category',
			'screen_reader_text' => __( 'Post navigation' ),
			'aria_label'         => __( 'Posts' ),
			'class'              => 'post-navigation',
		)
	);

	$navigation = '';

	$previous = get_previous_post_link(
		'<div class="nav-previous">%link</div>',
		$args['prev_text'],
		$args['in_same_term'],
		$args['excluded_terms'],
		$args['taxonomy']
	);

	$next = get_next_post_link(
		'<div class="nav-next">%link</div>',
		$args['next_text'],
		$args['in_same_term'],
		$args['excluded_terms'],
		$args['taxonomy']
	);

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

	return $navigation;
}

adjacent links (related links)

Navigation pagination

Navigation