WordPress.org

Ready to get started?Download WordPress

Codex

Function Reference/paginate links

Contents

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'       => '?page=%#%',
	'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' => ''
); ?>

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

Return Values

mixed (array|string) 
String or array of page links.

Examples

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
$paged = ( get_query_var( 'paged' ) ) ? 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
) );
?>

Notes

Change Log

Source File

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

Related