wp_link_pages() – Function | Developer.WordPress.org

The formatted output of a list of pages.

Description

Displays page links for paginated posts (i.e. including the  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.

Uses	Description
_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 more Show less

Used by	Description
link_pages()`wp-includes/deprecated.php`	Print list of pages based on arguments.

Changelog

Version	Description
5.1.0	Added the `aria_current` argument.
1.2.0	Introduced.

User Contributed Notes

hearvox 9 years ago

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

Skip to note 10 content

hearvox 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
Example:
If the content of a page (or post) has at least one  tag (and this code is in The Loop), this prints linked page numbers (“Pages: 1 2 3”), without a link on current page number, and by default within <p> tags:
```
<?php wp_link_pages(); ?>
```
Log in to add feedback
Skip to note 11 content

hearvox 9 years ago

You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note
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>' ); ?>
```
Log in to add feedback
Skip to note 12 content

Steven Lin 5 years ago

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:

Default Usage

Displays page-links by default with paragraph tags before and after, using Next page and Previous page, listing them with page numbers as Page 1, Page 2 and so on.
```
<?php wp_link_pages(); ?>
```
Log in to add feedback
Skip to note 13 content

Steven Lin 5 years ago

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:

Page-links in Paragraph Tags
```
<?php wp_link_pages('before=<p>&after=</p>&next_or_number=number&pagelink=page %'); ?>
```
Log in to add feedback
Skip to note 14 content

Steven Lin 5 years ago

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:

Page-links in DIV

Displays page-links in DIV for CSS reference as .
```
<?php wp_link_pages('before=<div id="page-links">&after=</div>'); ?>
```
Log in to add feedback
Skip to note 15 content

Steven Lin 5 years ago

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>',
	) );
?>
```
Log in to add feedback

Janak Patel 2 years ago

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

$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

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

In this article