WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

wp_link_pages()

wp_link_pages( string|array $args = '' ): string

In this article

Back to top

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

View all references View on Trac View on GitHub

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.

UsesDescription
_wp_link_page()wp-includes/post-template.php

Helper function for wp_link_pages() .

esc_attr()wp-includes/formatting.php

Escaping for HTML attributes.

wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.

apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 2 moreShow less
Used byDescription
link_pages()wp-includes/deprecated.php

Print list of pages based on arguments.

Changelog

VersionDescription
5.1.0Added the aria_current argument.
1.2.0Introduced.

User Contributed Notes

  1. Skip to note 9 content
    hearvox
    You must log in to vote on the helpfulness of this noteVote results for this note: 2You must log in to vote on the helpfulness of this note

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

  7. Skip to note 15 content
    Steven Lin
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    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>',	) ); ?>
  8. Skip to note 16 content
    Janak Patel
    You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

    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.