wp_link_pages( string|array $args = '' )
The formatted output of a list of pages.
Description 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 Parameters
- $args
-
(string|array) (Optional) 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 value: ''
- 'before'
Return Return
(string) Formatted output in HTML.
Source Source
File: wp-includes/post-template.php
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 arguments for page links for paginated posts. */ $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 $args An array of arguments. */ $html = apply_filters( 'wp_link_pages', $output, $args ); if ( $parsed_args['echo'] ) { echo $html; } return $html; }
Expand full source code Collapse full source code View on Trac
Changelog Changelog
Version | Description |
---|---|
5.1.0 | Added the aria_current argument. |
1.2.0 | Introduced. |
User Contributed Notes User Contributed Notes
You must log in before being able to contribute a note or feedback.
Use previous/next option (instead of page numbers); customize text, HTML, and classes:
Expand full source codeCollapse full source code
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.)
Example:
If the content of a page (or post) has at least one
<!--nextpage-->
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:Display page-links within other HTML tags:
Prints page links as list items within an unordered list, and with custom class names: