wp_link_pages()WP 1.2.0

The formatted output of a list of pages.

Displays page links for paginated posts (i.e. including the <!--nextpage--> Quicktag one or more times). This tag must be within The Loop.

Return

String. Formatted output in HTML.

Usage

wp_link_pages( $args );
$args(string|array)

Array or string of default arguments.

Default: ''

  • before(string)
    HTML or text to prepend to each link.
    Default: <p> Pages:

  • after(string)
    HTML or text to append to each link.
    Default: </p>

  • link_before(string)
    HTML or text to prepend to each link, inside the <a> tag. Also prepended to the current item, which is not linked.
    Default: ''

  • link_after(string)
    HTML or text to append to each Pages link inside the <a> tag. Also appended to the current item, which is not linked.
    Default: ''

  • aria_current(string)
    The value for the aria-current attribute. Possible values are 'page', 'step', 'location', 'date', 'time', 'true', 'false'.
    Default: 'page'

  • next_or_number(string)
    Indicates whether page numbers should be used. Valid values are number and next.
    Default: 'number'

  • separator(string)
    Text between pagination links.
    Default: ' '

  • nextpagelink(string)
    Link text for the next page link, if available.
    Default: 'Next Page'

  • previouspagelink(string)
    Link text for the previous page link, if available.
    Default: 'Previous Page'

  • pagelink(string)
    Format string for page numbers. The % in the parameter string will be replaced with the page number, so 'Page %' generates "Page 1", "Page 2", etc.
    Default: '%', just the page number

  • echo(int|true|false)
    Whether to echo or not. Accepts 1|true or 0|false.
    Default: 1|true

Examples

0

#1 Basic use [auto-translate]

Let's display page navigation with default settings, i.e. in the tag <p> using page links (page 1, page 2) and navigation links "back", "Forward".

<?php wp_link_pages(); ?>
0

#2 Adding a page break button to TyniMCE (Visual Editor)

Such a button is provided by WordPress, but it does not appear. So all we need to do is add the name of this button to the array via hook, WP will do the rest... To do this you need to insert this code in functions.php theme:

## Adding a page break button to TyniMCE 
add_filter('mce_buttons', 'mce_page_break');

function mce_page_break( $mce_buttons ){

	$pos = array_search('wp_more', $mce_buttons, true);

	if( $pos !== false ) {
		$buttons = array_slice( $mce_buttons, 0, $pos );
		$buttons[] = 'wp_page';
		$mce_buttons = array_merge( $buttons, array_slice($mce_buttons, $pos) );
	}

	return $mce_buttons;
}

The result will be this button:

"Next page" button in the WordPress visual editor
0

#3 Wrap the links in the <div> tag and change the text of each link to "page #": [auto-translate]

<?php wp_link_pages('before=<div id="page-links">&after=</div>&pagelink=page %'); ?>
0

#4 Use previous/next option (instead of page numbers)

<?php
$args = array (
	'before'            => '<div class="page-links-XXX"><span class="page-link-text">' . __( 'More pages: ', 'textdomain' ) . '</span>',
	'after'             => '</div>',
	'link_before'       => '<span class="page-link">',
	'link_after'        => '</span>',
	'next_or_number'    => 'next',
	'separator'         => ' | ',
	'nextpagelink'      => __( 'Next »', 'textdomain' ),
	'previouspagelink'  => __( '« Previous', 'textdomain' ),
);

wp_link_pages( $args );
?>

The above displays on the page as this:

More pages: « Previous | Next »

“Previous” and “Next” links will not print if on the first or last pages, respectively.

0

#5 Display page-links within other HTML tags:

Prints page links as list items within an unordered list, and with custom class names:

<?php wp_link_pages( 'before=<ul class="page-links">&after=</ul>&link_before=<li class="page-link">&link_after=</li>' ); ?>
0

#6 Use this function in content templates

This code snippet can be added directly to your singular.php, single.php, ... files in the position you want your pagination to display.

<?php wp_link_pages( array(
	'before'      => '<div class="page-links"><span class="page-links-title">' . __( 'Pages:', 'twentyfourteen' ) . '</span>',
	'after'       => '</div>',
	'link_before' => '<span>',
	'link_after'  => '</span>',
	) );
?>

Notes

  • Global. Int. $page
  • Global. Int. $numpages
  • Global. Int. $multipage
  • Global. Int. $more

Changelog

Since 1.2.0 Introduced.
Since 5.1.0 Added the aria_current argument.

wp_link_pages() code WP 6.4.3

function wp_link_pages( $args = '' ) {
	global $page, $numpages, $multipage, $more;

	$defaults = array(
		'before'           => '<p class="post-nav-links">' . __( 'Pages:' ),
		'after'            => '</p>',
		'link_before'      => '',
		'link_after'       => '',
		'aria_current'     => 'page',
		'next_or_number'   => 'number',
		'separator'        => ' ',
		'nextpagelink'     => __( 'Next page' ),
		'previouspagelink' => __( 'Previous page' ),
		'pagelink'         => '%',
		'echo'             => 1,
	);

	$parsed_args = wp_parse_args( $args, $defaults );

	/**
	 * Filters the arguments used in retrieving page links for paginated posts.
	 *
	 * @since 3.0.0
	 *
	 * @param array $parsed_args An array of page link arguments. See wp_link_pages()
	 *                           for information on accepted arguments.
	 */
	$parsed_args = apply_filters( 'wp_link_pages_args', $parsed_args );

	$output = '';
	if ( $multipage ) {
		if ( 'number' === $parsed_args['next_or_number'] ) {
			$output .= $parsed_args['before'];
			for ( $i = 1; $i <= $numpages; $i++ ) {
				$link = $parsed_args['link_before'] . str_replace( '%', $i, $parsed_args['pagelink'] ) . $parsed_args['link_after'];
				if ( $i != $page || ! $more && 1 == $page ) {
					$link = _wp_link_page( $i ) . $link . '</a>';
				} elseif ( $i === $page ) {
					$link = '<span class="post-page-numbers current" aria-current="' . esc_attr( $parsed_args['aria_current'] ) . '">' . $link . '</span>';
				}
				/**
				 * Filters the HTML output of individual page number links.
				 *
				 * @since 3.6.0
				 *
				 * @param string $link The page number HTML output.
				 * @param int    $i    Page number for paginated posts' page links.
				 */
				$link = apply_filters( 'wp_link_pages_link', $link, $i );

				// Use the custom links separator beginning with the second link.
				$output .= ( 1 === $i ) ? ' ' : $parsed_args['separator'];
				$output .= $link;
			}
			$output .= $parsed_args['after'];
		} elseif ( $more ) {
			$output .= $parsed_args['before'];
			$prev    = $page - 1;
			if ( $prev > 0 ) {
				$link = _wp_link_page( $prev ) . $parsed_args['link_before'] . $parsed_args['previouspagelink'] . $parsed_args['link_after'] . '</a>';

				/** This filter is documented in wp-includes/post-template.php */
				$output .= apply_filters( 'wp_link_pages_link', $link, $prev );
			}
			$next = $page + 1;
			if ( $next <= $numpages ) {
				if ( $prev ) {
					$output .= $parsed_args['separator'];
				}
				$link = _wp_link_page( $next ) . $parsed_args['link_before'] . $parsed_args['nextpagelink'] . $parsed_args['link_after'] . '</a>';

				/** This filter is documented in wp-includes/post-template.php */
				$output .= apply_filters( 'wp_link_pages_link', $link, $next );
			}
			$output .= $parsed_args['after'];
		}
	}

	/**
	 * Filters the HTML output of page links for paginated posts.
	 *
	 * @since 3.6.0
	 *
	 * @param string       $output HTML output of paginated posts' page links.
	 * @param array|string $args   An array or query string of arguments. See wp_link_pages()
	 *                             for information on accepted arguments.
	 */
	$html = apply_filters( 'wp_link_pages', $output, $args );

	if ( $parsed_args['echo'] ) {
		echo $html;
	}
	return $html;
}