Using WordPress ‘paginate_links()’ PHP function

by

The paginate_links() WordPress PHP function retrieves paginated links for archive post pages. It can technically be used to create paginated link lists for any area, but it’s most commonly used on archive post pages. It controls the format of the returned value and can return a plain string, an array, or a list.

Usage

To use the paginate_links() function, here’s a basic example:

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

Parameters

  • $args (string|array) – An array or string of arguments for generating paginated links for archives.
    • base (string) – The base of the paginated url.
    • format (string) – The format for the pagination structure.
    • total (int) – The total amount of pages. Default is the value WP_Query’s max_num_pages or 1.
    • current (int) – The current page number. Default is ‘paged’ query var or 1.
    • aria_current (string) – The value for the aria-current attribute.
    • show_all (bool) – Whether to show all pages. Default false.
    • end_size (int) – How many numbers on either the start and the end list edges. Default 1.
    • mid_size (int) – How many numbers to either side of the current pages. Default 2.
    • prev_next (bool) – Whether to include the previous and next links in the list. Default true.
    • prev_text (string) – The previous page text. Default ‘« Previous’.
    • next_text (string) – The next page text. Default ‘Next »’.
    • type (string) – Controls format of the returned value. Possible values are ‘plain’, ‘array’ and ‘list’. Default is ‘plain’.
    • add_args (array) – An array of query args to add. Default false.
    • add_fragment (string) – A string to append to each link.
    • before_page_number (string) – A string to appear before the page number.
    • after_page_number (string) – A string to append after the page number.

More information

See WordPress Developer Resources: paginate_links()

Examples

Basic Pagination

This example generates a basic pagination for your pages or posts.

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

Custom Pagination Text

This example shows how to customize the previous and next text in the pagination.

echo paginate_links( array(
    'prev_text' => __('« Prev'),
    'next_text' => __('Next »'),
) );

This example demonstrates the basic usage of paginate_links, displaying the pagination with default settings.

echo paginate_links();

Customizing pagination

This example customizes the pagination with a custom base URL, format, and number of pages.

echo paginate_links( array(
    'base' => 'http://example.com/custom_posts%_%',
    'format' => '?page=%#%',
    'total' => 10,
    'current' => 1
));

Displaying pagination in an unordered list

This example displays the pagination as an unordered list.

echo paginate_links( array(
    'type' => 'list'
));

Custom previous and next text

This example customizes the previous and next text labels.

echo paginate_links( array(
    'prev_text' => '« Previous',
    'next_text' => 'Next »'
));

Show all pages in pagination

This example shows all the pages in the pagination instead of a short list of pages near the current page.

echo paginate_links( array(
    'show_all' => true
));