paginate_links( string|array $args = ” ): string|string[]|void

User Contributed Notes

1. Skip to note 8 content

   Codex 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 8You must log in to vote on the helpfulness of this note

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

   • When using PHP >= 8, the types are important. You have to use $big = ‘999999999’;, otherwise the first string replacement will fail. Other then that, the example works perfectly.

     Iulia Cazan 1 year ago
2. Skip to note 9 content

   Codex 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

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

   • This should be the default to avoid a lawsuit (Which we’re going through right now so don’t think it wont happen to you!). Additionally you need the previous and next links to say what they are:

      'prev_text' => is_rtl() ? 'Previous Page →' : 'Previous Page ←', 'next_text' => is_rtl() ? 'Next Page ←' : 'Next Page →', 

     thedoctore 2 years ago
   • When using PHP 8, the types are important. You have to use $big = '999999999';, otherwise the first string replacement will fail.

     Iulia Cazan 1 year ago
3. Skip to note 10 content

   Hay 4 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 5You must log in to vote on the helpfulness of this note

   You might notice that paginate_links always gives back HTML, even if you’re setting type to array, which makes it a bit hard if you want to completely customise the HTML structure of your pagination. I wrote a little function that gives you back an array of objects instead of HTML that might make this a bit easier.

   function wpdocs_get_paginated_links( $query ) {
       // When we're on page 1, 'paged' is 0, but we're counting from 1,
       // so we're using max() to get 1 instead of 0
       $currentPage = max( 1, get_query_var( 'paged', 1 ) );
   
       // This creates an array with all available page numbers, if there
       // is only *one* page, max_num_pages will return 0, so here we also
       // use the max() function to make sure we'll always get 1
       $pages = range( 1, max( 1, $query->max_num_pages ) );
   
       // Now, map over $pages and return the page number, the url to that
       // page and a boolean indicating whether that number is the current page
       return array_map( function( $page ) use ( $currentPage ) {
           return ( object ) array(
               "isCurrent" => $page == $currentPage,
               "page" => $page,
               "url" => get_pagenum_link( $page )
           );
       }, $pages );
   }

   And use it like this (given that $query is the name of your custom query):

   <ul>
       <?php foreach( wpdocs_get_paginated_links( $query ) as $link ) : ?>
       <li>
           <?php if ( $link->isCurrent ): ?>
               <strong><?php _e( $link->page ) ?></strong>
           <?php else : ?>
               <a href="<?php esc_attr_e( $link->url ) ?>">
                   <?php _e( $link->page ) ?>
               </a>
           <?php endif; ?>
       </li>
       <?php endforeach; ?>
   </ul>
4. Skip to note 11 content

   Binsaifullah 6 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   // first create a function 
   function pagainate_link_function(){
   	global $wp_query;
   	echo paginate_links(array(
   		'current'=>max(1,get_query_var('paged')),
   		'total'=>$wp_query->max_num_pages,
   		'type'=>'list', //default it will return anchor
   	));
   }
   
   // Now call this function in your desired place
5. Skip to note 12 content

   Sean Leavey 6 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 1You must log in to vote on the helpfulness of this note

   Note that the base argument should be fully qualified, e.g. https://example.com/my-post/%_%#some-id, not just %_%#some-id.

   If the base argument doesn’t contain the absolute URL, then when you are on the second page the link to the first page will not work; instead it will link to the current page. This is because the “Previous” link is set to the base argument with the %_% part removed, and no extra ?paged=%#% part added. Your browser then interprets this to mean the current page, so the “Previous” link points to the current page.
6. Skip to note 13 content

   Codex 9 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: 0You must log in to vote on the helpfulness of this note

   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
   ) );
   ?>
7. Skip to note 14 content

   Chetan Prajapati 7 years ago

   You must log in to vote on the helpfulness of this noteVote results for this note: -3You must log in to vote on the helpfulness of this note

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

   Aligned array items properly based on WPCS.