WordPress.org

Languages: English • 日本語 (Add your language)

Description

Retrieve paginated link for archive post pages. Technically, the function can be used to create paginated link list for any area ( e.g.: « Prev 1 … 3 4 5 6 7 … 9 Next » )

Usage

<?php echo paginate_links( $args ); ?>

Default Arguments

<?php $args = array(
	'base'               => '%_%',
	'format'             => '?paged=%#%',
	'total'              => 1,
	'current'            => 0,
	'show_all'           => false,
	'end_size'           => 1,
	'mid_size'           => 2,
	'prev_next'          => true,
	'prev_text'          => __('« Previous'),
	'next_text'          => __('Next »'),
	'type'               => 'plain',
	'add_args'           => false,
	'add_fragment'       => '',
	'before_page_number' => '',
	'after_page_number'  => ''
); ?>

Parameters

Even if the whole arguments array is marked optional, the function will output nothing if you do not specify the needed arguments.

base

(string) (optional) Used to reference the url, which will be used to create the paginated links. The default value '%_%' in 'http://example.com/all_posts.php%_%' is replaced by 'format' argument (see below).

Default: '%_%'

format

(string) (optional) Used for Pagination structure. The default value is '?page=%#%', If using pretty permalinks this would be '/page/%#%', where the '%#%' is replaced by the page number.

Default: '?page=%#%'

total

(integer) (optional) The total amount of pages.

Default: 1

current

(integer) (optional) The current page number.

Default: 0

show_all

(boolean) (optional) If set to True, then it will show all of the pages instead of a short list of the pages near the current page. By default, the 'show_all' is set to false and controlled by the 'end_size' and 'mid_size' arguments.

Default: False

end_size

(integer) (optional) How many numbers on either the start and the end list edges.

Default: 1

mid_size

(integer) (optional) How many numbers to either side of current page, but not including current page.

Default: 2

prev_next

(boolean) (optional) Whether to include the previous and next links in the list or not.

Default: True

prev_text

(string) (optional) The previous page text. Works only if 'prev_next' argument is set to true.

Default: __('« Previous')

next_text

(string) (optional) The next page text. Works only if 'prev_next' argument is set to true.

Default: __('Next »')

type

(string) (optional) Controls format of the returned value. Possible values are:

• 'plain' - A string with the links separated by a newline character.
• 'array' - An array of the paginated link list to offer full control of display.
• 'list' - Unordered HTML list.

Default: 'plain'

add_args

(array) (optional) An array of query args to add.

Default: false

add_fragment

(string) (optional) A string to append to each link.

Default: None

before_page_number

(string) (optional) A string to appear before the page number.

Default: None

after_page_number

(string) (optional) A string to append after the page number.

Default: None

Return Values

mixed (array|string) 

String or array of page links.

Examples

• See example under paginate_comments_links().

Basic Example

To add pagination to your search results and archives, you can use the following example:

<?php
global $wp_query;

$big = 999999999; // need an unlikely integer

echo paginate_links( array(
	'base' => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
	'format' => '?paged=%#%',
	'current' => max( 1, get_query_var('paged') ),
	'total' => $wp_query->max_num_pages
) );
?>

Example With a Custom Query

When querying a loop with new WP_Query set the 'total' parameter to the max_num_pages property of the WP_Query object.

Example of a custom query:

<?php
//Protect against arbitrary paged values
$paged = ( get_query_var( 'paged' ) ) ? absint( get_query_var( 'paged' ) ) : 1;

$args = array(
	'posts_per_page' => 5,
	'category_name' => 'gallery',
	'paged' => $paged,
);

$the_query = new WP_Query( $args );
?>
<!-- the loop etc.. -->

Example of paginate_links parameters adapted to the custom query above:

<?php
$big = 999999999; // need an unlikely integer

echo paginate_links( array(
	'base' => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
	'format' => '?paged=%#%',
	'current' => max( 1, get_query_var('paged') ),
	'total' => $the_query->max_num_pages
) );
?>

Improving Accessibility

To add context to the numbered links to ensure that screen reader users understand what the links are for:

<?php
global $wp_query;

$big = 999999999; // need an unlikely integer
$translated = __( 'Page', 'mytextdomain' ); // Supply translatable string

echo paginate_links( array(
	'base' => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
	'format' => '?paged=%#%',
	'current' => max( 1, get_query_var('paged') ),
	'total' => $wp_query->max_num_pages,
        'before_page_number' => '<span class="screen-reader-text">'.$translated.' </span>'
) );
?>

Notes

• See Also: Enhanced Comment Display

Change Log

• Since: 2.1.0

Source File

paginate_links() is located in wp-includes/general-template.php.

Related

• Article: Pagination
• Function: posts_nav_link()
• Function: next_posts_link()
• Function: previous_posts_link()
• Function: get_next_posts_link()
• Function: get_previous_posts_link()
• Function: paginate_links()

• Function: wp_link_pages()
• Function: next_post_link()
• Function: previous_post_link()
• Function: next_image_link()
• Function: previous_image_link()

• Function: the_posts_pagination()
• Function: get_the_posts_pagination()

• Function: the_post_navigation()
• Function: get_the_post_pagination()

• Article: Making Custom Queries using Offset and Pagination