wp_link_pages( string|array $args =  ): string

The formatted output of a list of pages.

Description

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

Parameters

$argsstring|arrayoptional
Array or string of default arguments.
  • before string
    HTML or text to prepend to each link. Default is <p> Pages:.
  • after string
    HTML or text to append to each link. Default is </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.
  • 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.
  • aria_current string
    The value for the aria-current attribute. Possible values are 'page', 'step', 'location', 'date', 'time', 'true', 'false'. Default is 'page'.
  • next_or_number string
    Indicates whether page numbers should be used. Valid values are number and next. Default is 'number'.
  • separator string
    Text between pagination links. Default is ‘ ‘.
  • nextpagelink string
    Link text for the next page link, if available. Default is ‘Next Page’.
  • previouspagelink string
    Link text for the previous page link, if available. Default is ‘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.
    Defaults to '%', just the page number.
  • echo int|bool
    Whether to echo or not. Accepts 1|true or 0|false. Default 1|true.

Default:''

Return

string Formatted output in HTML.

Source

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;
}

Hooks

apply_filters( ‘wp_link_pages’, string $output, array|string $args )

Filters the HTML output of page links for paginated posts.

apply_filters( ‘wp_link_pages_args’, array $parsed_args )

Filters the arguments used in retrieving page links for paginated posts.

apply_filters( ‘wp_link_pages_link’, string $link, int $i )

Filters the HTML output of individual page number links.

Changelog

VersionDescription
5.1.0Added the aria_current argument.
1.2.0Introduced.

User Contributed Notes

  1. Skip to note 9 content

    Use previous/next option (instead of page numbers); customize text, HTML, and classes:

    <?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 &raquo', 'textdomain' ),
    	'previouspagelink'	=> __( '&laquo 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.)

  2. Skip to note 15 content

    Migrated from Codex:

    Adding wp_link_pages in content.php

    This code snippet can be added directly to your content.php or single.php file 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>',
    	) );
    ?>
  3. Skip to note 16 content

    For fully customized single post pagination

    • You can simply takeout as String by doing following
    •  $pagination_html = wp_link_pages( array( 'echo' => 0 ) ); 
    • Another trick you can do if you want to have pagination looks like this:
    • « Previous 1 2 3 Next »

       wp_link_pages( array(
      	'before'         => '--your input--',
      	'after'          => '--your input--',
      	'link_before'    => '--your input--',
      	'link_after'     => '--your input--',
      	'next_or_number' => 'next', // option to output numbers or next/prev button
      	'separator'	 => wp_link_pages( array( // trick 
      		'before'      => '--your input--',
      		'after'       => '--your input--',
      		'link_before' => '--your input--',
      		'link_after'  => '--your input--',
      		'echo'        => 0,
      	) ),
      	'nextpagelink'	  => __( 'Next »', 'textdomain' ),
      	'previouspagelink' => __( '« Previous', 'textdomain' ),
      	'echo'             => 0,
      ) );
    • Note: the values define in before, after arg is work as as an enclosure but the main thing to consider is that the values of link_before and link_after are set inside the anchor tag so no direct way to wrap the anchor tag, refer the below explanation
    •     	[before]
                  <a href='...' rel="nofollow ugc"> [link_before] 1 [link_after]</a>
      			<span class="post-page-numbers current" aria-current="page">2</span>   // current Page
                  <a href='...' rel="nofollow ugc"> [link_before] 3 [link_after]</a>
      		[after]        
    • There is no direct way defined at the function wp_link_pages to add HTML before every anchor tag.
      Simple hack for that can be search and replace for example
    $pagination_html = str_replace( '<a', '<li><a', $pagination_html );
    $pagination_html = str_replace( '</a>', '</a></li>', $pagination_html );
    $pagination_html = str_replace( '<span', '<li><span', $pagination_html );
    echo str_replace( '</span>', '</span></li>', $pagination_html );

    or

    $search_arr = array( '<a', '</a>', '<span', '</span>' );
    $replace_arr = array( '<li><a', '</a></li>', '<li class="active"><span', '</span></li>' );
    
    echo str_replace( $search_arr, $replace_arr, $pagination_html );

    to wrap all page numbers and current page number inside a list-item tag

You must log in before being able to contribute a note or feedback.