Skip to main content
Easily create better & faster websites with the Total WordPress Theme Learn More
(opens a new tab)
Tutorials

How To Add Pagination To Your WordPress Theme

If you are looking to add pagination support to your WordPress theme with cool numbers instead of the default next & previous post, you can do so using the famous PageNavi plugin, however, I much prefer adding pagination manually to my themes so people don’t have to go searching for a plugin. It also helps keep the site faster without all the external scripts and CSS.

Luckily there is a great function in wordpress called “paginate_links” which was added in WordPress 2.1 and will allow you to create a paginated style navigation for any query on your site. Here is a quick tutorial for adding a simple page navigation to your theme that looks just like the pagination in my Total WordPressTheme.

Pagination PHP

Simply add the following code at the end of your functions.php file (or whatever file in your theme where you want to keep it).

// Numbered Pagination
if ( !function_exists( 'wpex_pagination' ) ) {
	
	function wpex_pagination() {
		
		$prev_arrow = is_rtl() ? '→' : '←';
		$next_arrow = is_rtl() ? '←' : '→';
		
		global $wp_query;
		$total = $wp_query->max_num_pages;
		$big = 999999999; // need an unlikely integer
		if( $total > 1 )  {
			 if( !$current_page = get_query_var('paged') )
				 $current_page = 1;
			 if( get_option('permalink_structure') ) {
				 $format = 'page/%#%/';
			 } else {
				 $format = '&paged=%#%';
			 }
			echo paginate_links(array(
				'base'			=> str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
				'format'		=> $format,
				'current'		=> max( 1, get_query_var('paged') ),
				'total' 		=> $total,
				'mid_size'		=> 3,
				'type' 			=> 'list',
				'prev_text'		=> $prev_arrow,
				'next_text'		=> $next_arrow,
			 ) );
		}
	}
	
}

View All Parameters

Pagination CSS

Copy the following CSS and paste into your style.css file.

ul.page-numbers {
    list-style: none;
    margin: 0;
}

.page-numbers:after {
    content: ".";
    display: block;
    clear: both;
    visibility: hidden;
    line-height: 0;
    height: 0;
}

ul.page-numbers li {
    display: block;
    float: left;
    margin: 0 4px 4px 0;
    text-align: center;
}

.page-numbers a,
.page-numbers span {
    line-height: 1.6em;
    display: block;
    padding: 0 6px;
    height: 18px;
    line-height: 18px;
    font-size: 12px;
    text-decoration: none;
    font-weight: 400;
    cursor: pointer;
    border: 1px solid #ddd;
    color: #888;
}

.page-numbers a span { padding: 0 }

.page-numbers a:hover,
.page-numbers.current,
.page-numbers.current:hover {
    color: #000;
    background: #f7f7f7;
    text-decoration: none;
}

.page-numbers:hover { text-decoration: none }

Adding The Pagination Function To Your Theme

To call back the pagination function it’s really simple. All you have to do is add the following code to your theme files where you want to show any sort of pagination. The most common are your index.php, home.php, category.php, tags.php, archive.php and search.php. But if you have any custom page templates with pagination support, you’ll want to add them here.

Replace default pagination with the following (normally located somewhere after endif ):

<?php wpex_pagination(); ?>

Custom Queries?

If you are creating a custom query using WP_Query this function won’t work unless you’ve defined your query in the $wp_query variable (which is bad, don’t do it). To fix it, I generally create new queries like the following:

$wpex_query = new WP_Query( $args );

This way I can alter the main pagination function to look for the variable when creating the pagination, example (editing the first snippet):

global $wp_query, $wpex_query;
if ( $wpex_query ) {
    $total = $wpex_query->max_num_pages;
} else {
    $total = $wp_query->max_num_pages;
}

Update: In this example I check for the global variable…However you could simply pass the query variable directly to the wpex_pagination function which is probably a better choice 😉

64 Comments
  1. Anthony · 12 years ago

    So I figured out how to navigate around the Pytheas theme. Suuuuper cool theme btw! I was just thinking it would awesome if one could paginate the home (portfolio) page. If I set my posts to like say a hundred, then it would automatically create an additional page. Thumbs up guys!!! Good work!!!

    • Kyla · 12 years ago

      We’re glad you like the theme! It’s definitely possible but it would have to reload the page… the best option would be an ajax load more option.

    • anam · 11 years ago

      firstly i enter the above mentioned code at the end of the functions.php and press the upgrade button then i found this error
      Parse error: syntax error, unexpected ‘clear’ (T_STRING), expecting ‘,’ or ‘;’ in /home4/raza/public_html/easytipstricks/wp-content/themes/goodnews47/functions.php on line 22
      wtf is this?

      • AJ Clarke · 11 years ago

        This was a very old post, I’ve completely updated it and made it better 😉

  2. Anthony · 11 years ago

    Thanks Kyla!!! Im looking into that now.

  3. wiki · 11 years ago

    this is not work in your gopress theme

    • AJ Clarke · 11 years ago

      The GoPress theme has pagination built-in. And actually since this post was created a long time ago…there is now a better way using the core function paginate_links(), learn more on the Codex.

      ps: Have you seen the updated GoPress Theme?

  4. Kristoff · 11 years ago

    Thank you so much, every other solution I had found was broken. This was the one that worked perfectly.

  5. Jonathan Lafleur · 10 years ago

    I liked this function but I was hating using $wpex_query for every custom query, so I modified a little bit your basic function, for people interested here is the complete code.

    • AJ Clarke · 10 years ago

      This is nice Jonathan, but you can tweak it a bit. Because you are passing the variable into the function no need to call it globally. There isn’t also a need for a multi-level variable. You could just do it like this:

      function wpex_pagination( $the_query = NULL ) {
        global $wp_query;
        $the_query = $the_query ? $the_query : $wp_query;
        $total = $the_query->max_num_pages;
      

      And of course your function would be like this…

      wpex_pagination( $your_custom_query_var );
      
      • Jonathan Lafleur · 10 years ago

        You are totally right ! I was looking really too far ! Thank’s

  6. ken · 10 years ago

    Hello.
    I would like to add pagination to three pages in my wordpress website I’m building. I’m new to wordpress and actually learning a lot. I do appreciate the codes given on this site. I downloaded the wp-pagenavi plugin, however I did not activate it yet. Can someone give me step by step instruction on where to insert the codes? ( Jupiter wordpress)
    I was informed to go into the FTP, I can give you access if needed

    • AJ Clarke · 10 years ago

      99% of themes include pagination by default, are you sure your theme doesn’t already have pagination built-in?

      If you do want someone to assist with the code I would recommend hiring a developer.

  7. Oleg · 10 years ago

    Thanks a lot! I use it for my custom query. It works perfect!

  8. Filip van Hoeckel · 10 years ago

    Works great, although your code does need ; after &larr and &rarr, otherwise it would just output the string. Cheers.

    • AJ Clarke · 10 years ago

      Oh yes, thanks for letting me know about the typo!

  9. pupuse · 10 years ago

    Hi AJ Clarke,

    Thank you for this code! I probably do something wrong, but when I click the second page, it does show the same posts as on the first page. i did read some articles bout query_posts, but I do not think I use that. Do you maybe have any idea why it doesn’t work correctly and where I have to look?

    • AJ Clarke · 10 years ago

      If you can share your loop with me, I’ll help out. Link to a gist or pastebin to share the code, please don’t paste it in the comments it may get messed up.

  10. pupuse · 10 years ago

    Hi AJ Clarke,

    Thank you very much for the code. But I only get the same posts on page 1 as I get on page two. Did I do something wrong?

    • AJ Clarke · 10 years ago

      That depends on your loop itself. For example the standard loop is defined at Settings->Reading, while a custom loop would be the posts_per_page parameter.

      • pupuse · 10 years ago

        In my settings -> reading -> Blog pages show at most is 8. At this moment I have 10 posts, so two of them should show up at page two. Before there no pagination, so I only used your code and placed this in functions.php, index.php and slyles.css of my theme. I searched in these files for ‘posts_per_page” but did not find a result.

        I hope you can help.

        • AJ Clarke · 10 years ago

          Looks like pagination is working now 😉 I see 8 posts per page and 2 pages.

          • pupuse · 10 years ago

            Unfortunately when you click on the second page, you will see the same posts as on the first page.

            • AJ Clarke · 10 years ago

              If this is on the homepage, then the issue is probably that your custom query is conflicting with the main query, you’ll probably have to use $wp_query – $wp_query = new WP_Query( $args ) – and then reset it after the loop. Pagination with custom queries on the homepage is tricky but if you google it you’ll find some useful info.

  11. Geraldi · 10 years ago

    I get the same posts on page 2,3,4… as I get on page 1.

    I am using this code in my custom blog page template [edited]

    plz help me

    • AJ Clarke · 10 years ago

      Like I said pagination is very tricky on the homepage with a custom query, you’ll probably need to change ‘wpex_query’ to ‘wp_query’ then add some extra arguments to reset pagination, example:

      global $post, $paged, $more;
      $more = 0;
      if ( get_query_var( 'paged' ) ) {
      	$paged = get_query_var( 'paged' );
      } else if ( get_query_var( 'page' ) ) {
      	$paged = get_query_var( 'page' );
      } else {
      	$paged = 1;
      }
      // Query posts
      $wp_query = new WP_Query(
      	array(
      		'post_type'		=> 'post',
      		'paged'			=> $paged,
      	)
      );
      
  12. Sarkari naukri · 10 years ago

    Hi i am using Open estate wordpress theme but there theme pagination is not working please help me how to use pagination in that theme.

    • AJ Clarke · 10 years ago

      That is a premium theme, you should contact the developer for support and they should be able to help you.

  13. jaime // the briny · 10 years ago

    Hi there, AJ. Your tutorial was a great help to me; I managed to get the numeric pagination in place on my blog. Thank you!

    I just have one problem and I’m wondering if you might know how to fix it. I’m using a Twenty Thirteen child theme which utilizes padding to specify the placement of the entry content. I’ve aligned the numeric pagination span to be more or less inline with my entry content, but on mobile devices this padding causes a problem–the rest of my site’s content is squished down to take up half of the horizontal space it should, and the pagination area is forced to the right. I’ve tried using margins and percentage values (instead of pixels), but it seems to cause the same issue.

    Would you be able to recommend another way I can align the pagination span with my entry content?

    Thank you!

    • AJ Clarke · 10 years ago

      There is a massive padding added to left side of “ul.page-numbers”, that’s what’s causing the issue.

      • jaime // the briny · 10 years ago

        I’ve already identified that padding as the issue. What I was hoping to learn from you was a different approach for positioning the pagination span that wouldn’t cause problems (or that would be responsive) for mobile devices, while still keeping the placement I want for large screens. Any ideas you have would be greatly appreciated.

        • AJ Clarke · 10 years ago

          Sorry, I guess I didn’t really understand the issue then. All you need to do is move the code into the “entry-content” div (same div that the articles are in) because right now it spans 100% of the site.

          • jaime // the briny · 10 years ago

            No worries, and thanks for looking at it again. Unfortunately, I tried to move the code into the entry content div previously, but it registers the pagination under every individual post (instead of just under the last one).

            I’ve also tried inspecting the element on my mobile device in attempts to specify 0 padding for the responsive/small-screen page, but haven’t had any luck there, either.

            • AJ Clarke · 10 years ago

              Things look a bit off in the coding of this theme…So I went to look in your child theme and it appears you may have copied/pasted the code from the main theme to the child theme? This is a big no no. Make sure your child theme only has your edits! Anyway looking at the theme locally…the coding in twenty-13 is very limiting and not very good to be honest. You’ll need to make your own tweaks to get it working nicely, there doesn’t seem to be any way to add it into a div and be done with it. I would find a better theme 😉

  14. ddd · 10 years ago

    done the same process as directed above… but the custom page pagination isn’t working at all.

    • AJ Clarke · 10 years ago

      Double check your code and the loop. Also, if you are adding pagination to the front-page via a custom Query you may need to add some extra code.

  15. Amy · 10 years ago

    Ding ding ding ding! Hours of research, trying 100 different things, and found the solution for using paginate_links within a wp_query right here. Thank you!

    • Thom · 10 years ago

      Can you tell me more about that? I have try different theme from wpexplorer but the pagination of the portfolio still doesn t work! Now I installed the adapt theme . Is there a way to fix this problem? I

      • AJ Clarke · 10 years ago

        Is the pagination broken on my live demo? Because if it’s working on my live demo and not on your site then there is some sort of conflict on your end. If you can show me the URL where it’s broken on my live demo I’ll be glad to look and fix the issue.

  16. Morshedul Arefin · 10 years ago

    This is a great article and helped me a lot. Thank you very much Clarke to post this. Awesome job so far!!!

  17. Rifat Alom · 10 years ago

    Awesome

  18. Cathy Herardc · 10 years ago

    OMG. I entered the code and my blog has literally disappeared AND I can’t even get into my dashboard. What the heck?!?! Please help!

    • AJ Clarke · 10 years ago

      Sounds like there is a PHP error on the site, you’ll need to enable WP_Debug so you can see what the error is and fix it via FTP. If you aren’t a developer, be careful tweaking the code 😉 This is an advanced tutorial. Also don’t edit any code in the WordPress dashboard via the editor, it’s not good practice because you can get a white screen of death like this, make sure you do your edits in a real text editor (I use sublime text) then update your files via FTP (making a backup first) that way if you run into any issue you can quickly revert.

  19. Glen Michael · 10 years ago

    Hi AJ

    This is a great tutorial and worked well for me (after a little CSS tweaking to integrate more with my theme). Thank you for not making me use another plugin.

    Cheers
    Glen

  20. Bilqees Kenchi · 9 years ago

    Woooo its great, easy and simple coding my issue is solved now thanks for sharing

  21. Bill Ooy · 9 years ago

    I added this code to my custom taxonomy page. And it does show the pagination, but when I go the second page it gives a 404 error. I checked the slug settings and all but there shouldn’t be anything that interferes. Do you know anything what could cause this?

    • AJ Clarke · 8 years ago

      This generally happens if you have a slug conflict. Is there any other page, attachment, image, category…etc on the site with the same slug? Also I did update the code recently if you want to have a look.

  22. suresh · 9 years ago

    i had applied procedure what you have mentioned above but i can’t get pagination functionality into my home page can you please make video for that

    • AJ Clarke · 8 years ago

      Because of how WordPress works getting pagination to work on the homepage can be very tricky if you are using a static page. Are you using a static page? If so, you may have to consider disabling canonical redirection on the homepage using custom code like this:

      myprefix_home_pagination_fix( $redirect_url ) {
      	if ( is_paged() && is_singular() ) {
      		$redirect_url = false;
      	}
      	return $redirect_url;
      }
      add_filter( 'redirect_canonical', 'myprefix_home_pagination_fix' );
  23. coptictreasures · 9 years ago

    Hi,
    Thanks a lot for this code.
    can the pagination starts at page 0 ?
    so the first part is 0, then the second is 1..etc?
    the reason for this is that i want to put an online book for reading. i want to put the introduction on page 0, so chapter 1 becomes 1, chapter 2 becomes 2..etc
    otherwise, i will need to put the introduction and chapter 1 in the first part of the post, then it will become too long.

    cheers

    • AJ Clarke · 8 years ago

      Honestly I am not sure if that’s possible to do via the WordPress paginate_links function. But you could use javascript to loop through all your numbers and simply alter the number display while keeping the link intact. The only issue is the URL will still read page /page/1/…If you are able to locate a good solution please let me know as I am curious. Thanks!

  24. Tim B · 9 years ago

    A combination of this post, plus the archive.php template in the twentysixteen theme saved my life. I combined the two and remade my category.php file, which absolutely refused to work. BTW for anyone confused, the bumber of posts per page is controlled in settings > reading, its not a variable in the code. Thanks again!

  25. Iulian · 8 years ago

    Great! It works when no WordPress plugin get this think done.
    But I have an issue: How can I center the pagination?

    • AJ Clarke · 8 years ago

      You just have to tweak your CSS. Make the elements have a display of inline or inline-block and remove any floats then set the outer wrapper to text-align center. If you google “centering items with CSS” you may find a good article about that.

  26. Wordpress Developer · 7 years ago

    Really is very nice. I have a WordPress site and this article is very helpful. Thank you so much.

  27. Roee yossef · 7 years ago

    Really liked the article, right to the point. Thanks a lot ! 🙂

  28. Alexander · 7 years ago

    Thanks for sharing this great tutorial about pagination. I have seen a tutorial wpblog.com/use-wp_query-to-create-pagination/ and i am trying to add the code but i am doing something wrong. This is the code (removed by staff).

    • AJ Clarke · 7 years ago

      Hi,

      Have you tried the code from our post above? The code you mention has some issues, but more importantly you should only be using the core WordPress function paginate_links or the posts_nav_link functions for your pagination to prevent problems in the future and to make sure it’s best optimized.

  29. Tran Minh Tam · 5 years ago

    I’m using flatsome theme. I have searched many plugins (page-navi, WP-paginate, …) and many codes for paginations. But all of them don’t work in my theme.
    Can you help me to fix this?
    Thanks a lot!

    • Kyla · 5 years ago

      If you’re using the premium Flatsome theme from Themeforest I would suggest reaching out to the developer – they should be able to help 🙂

  30. testik · 5 years ago

    How to remove link to prev page?

    • Kyla · 5 years ago

      If you don’t want a previous link then you shouldn’t use the paginate_links function, instead you can use the next_posts_link function.

  31. David · 5 years ago

    Thanks for this code am giving it a try. hoping it will work for me.
    thanks in advance

  32. Irwin · 4 years ago

    thank you kindly!

Leave a Reply

Your email address will not be published. Required fields are marked *

Learn how your comment data is processed by viewing our privacy policy here.