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

Description

Parameters

$argsstring|arrayoptional

Array or string of default arguments.Default: ''

• $beforestringdefault: is <p> Pages:

  HTML or text to prepend to each link.

• $afterstringdefault: is </p>

  HTML or text to append to each link.

• $link_beforestringdefault: empty

  HTML or text to prepend to each link, inside the <a> tag. Also prepended to the current item, which is not linked.

• $link_afterstringdefault: empty

  HTML or text to append to each Pages link inside the <a> tag. Also appended to the current item, which is not linked.

• $aria_currentstringdefault: is 'page'

  The value for the aria-current attribute. Possible values are 'page', 'step', 'location', 'date', 'time', 'true', 'false'.

• $next_or_numberstringdefault: is 'number'

  Indicates whether page numbers should be used. Valid values are number and next.

• $separatorstringdefault: is ' '

  Text between pagination links.

• $nextpagelinkstringdefault: is 'Next Page'

  Link text for the next page link, if available.

• $previouspagelinkstringdefault: is 'Previous Page'

  Link text for the previous page link, if available.

• $pagelinkstring

  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.

• $echoint|booldefault: 1|true

  Whether to echo or not. Accepts 1|true or 0|false.

Return

string

Formatted output in HTML.

Hooks fired · 5

5 hooks fire while wp_link_pages() runs, in this order:

1. 1
   apply_filters( wp_link_pages_args )filterline 985 (+27 into the body)

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

2. 2
   apply_filters( wp_link_pages_link )filterline 1008 (+50 into the body)

   Filters the HTML output of individual page number links.

3. 3
   apply_filters( wp_link_pages_link )filterline 1022 (+64 into the body)

   Filters the HTML output of individual page number links.

4. 4
   apply_filters( wp_link_pages_link )filterline 1032 (+74 into the body)

   Filters the HTML output of individual page number links.

5. 5
   apply_filters( wp_link_pages )filterline 1047 (+89 into the body)

   Filters the HTML output of page links for paginated posts.

Uses · 5

• __()Retrieves the translation of $text.
• wp_parse_args()Merges user defined arguments into defaults array.
• apply_filters()Calls the callback functions that have been added to a filter hook.
• _wp_link_page()Helper function for wp_link_pages().
• esc_attr()Escaping for HTML attributes.

Used by · 2

• link_pages()Print list of pages based on arguments.
• render_block_core_post_content()Renders the `core/post-content` block on the server.

Source

View on Trac ↗View on GitHub ↗

958function wp_link_pages( $args = '' ) {959	global $page, $numpages, $multipage, $more;960 961	$defaults = array(962		'before'           => '<p class="post-nav-links">' . __( 'Pages:' ),963		'after'            => '</p>',964		'link_before'      => '',965		'link_after'       => '',966		'aria_current'     => 'page',967		'next_or_number'   => 'number',968		'separator'        => ' ',969		'nextpagelink'     => __( 'Next page' ),970		'previouspagelink' => __( 'Previous page' ),971		'pagelink'         => '%',972		'echo'             => 1,973	);974 975	$parsed_args = wp_parse_args( $args, $defaults );976 977	/**978	 * Filters the arguments used in retrieving page links for paginated posts.979	 *980	 * @since 3.0.0981	 *982	 * @param array $parsed_args An array of page link arguments. See wp_link_pages()983	 *                           for information on accepted arguments.984	 */985	$parsed_args = apply_filters( 'wp_link_pages_args', $parsed_args );986 987	$output = '';988	if ( $multipage ) {989		if ( 'number' === $parsed_args['next_or_number'] ) {990			$output .= $parsed_args['before'];991			for ( $i = 1; $i <= $numpages; $i++ ) {992				$link = $parsed_args['link_before'] . str_replace( '%', $i, $parsed_args['pagelink'] ) . $parsed_args['link_after'];993 994				if ( $i !== $page || ! $more && 1 === $page ) {995					$link = _wp_link_page( $i ) . $link . '</a>';996				} elseif ( $i === $page ) {997					$link = '<span class="post-page-numbers current" aria-current="' . esc_attr( $parsed_args['aria_current'] ) . '">' . $link . '</span>';998				}999 1000				/**1001				 * Filters the HTML output of individual page number links.1002				 *1003				 * @since 3.6.01004				 *1005				 * @param string $link The page number HTML output.1006				 * @param int    $i    Page number for paginated posts' page links.1007				 */1008				$link = apply_filters( 'wp_link_pages_link', $link, $i );1009 1010				// Use the custom links separator beginning with the second link.1011				$output .= ( 1 === $i ) ? ' ' : $parsed_args['separator'];1012				$output .= $link;1013			}1014			$output .= $parsed_args['after'];1015		} elseif ( $more ) {1016			$output .= $parsed_args['before'];1017			$prev    = $page - 1;1018			if ( $prev > 0 ) {1019				$link = _wp_link_page( $prev ) . $parsed_args['link_before'] . $parsed_args['previouspagelink'] . $parsed_args['link_after'] . '</a>';1020 1021				/** This filter is documented in wp-includes/post-template.php */1022				$output .= apply_filters( 'wp_link_pages_link', $link, $prev );1023			}1024			$next = $page + 1;1025			if ( $next <= $numpages ) {1026				if ( $prev ) {1027					$output .= $parsed_args['separator'];1028				}1029				$link = _wp_link_page( $next ) . $parsed_args['link_before'] . $parsed_args['nextpagelink'] . $parsed_args['link_after'] . '</a>';1030 1031				/** This filter is documented in wp-includes/post-template.php */1032				$output .= apply_filters( 'wp_link_pages_link', $link, $next );1033			}1034			$output .= $parsed_args['after'];1035		}1036	}1037

History

Introduced in 1.2.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 7.0.4 tag, from src/wp-includes/post-template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.