Better WordPress pagination
UPDATED 6/6/09: Added query string to work with search pagination.
Ever wanted to have better pagination controls in WordPress? Those “Newer posts / Older posts” links are a bit limited. Much better is the ubiquitous numbered list, a la Google’s results page.
There is at least one plugin for this. As ever, I’m keen to keep plugin overhead to a minimum, and where possible to just include a simple function in my custom themes for basic functionality like this. Here’s the function:
function pagination( $query, $baseURL = '' ) {
if ( ! $baseURL ) $baseURL = get_bloginfo( 'url' );
$page = $query->query_vars["paged"];
if ( !$page ) $page = 1;
$qs = $_SERVER["QUERY_STRING"] ? "?".$_SERVER["QUERY_STRING"] : "";
// Only necessary if there's more posts than posts-per-page
if ( $query->found_posts > $query->query_vars["posts_per_page"] ) {
echo '<ul class="paging">';
// Previous link?
if ( $page > 1 ) {
echo '<li class="previous"><a href="'.$baseURL.'page/'.($page-1).'/'.$qs.'">« previous</a></li>';
}
// Loop through pages
for ( $i=1; $i <= $query->max_num_pages; $i++ ) {
// Current page or linked page?
if ( $i == $page ) {
echo '<li class="active">'.$i.'</li>';
} else {
echo '<li><a href="'.$baseURL.'page/'.$i.'/'.$qs.'">'.$i.'</a></li>';
}
}
// Next link?
if ( $page < $query->max_num_pages ) {
echo '<li><a href="'.$baseURL.'page/'.($page+1).'/'.$qs.'">next »</a></li>';
}
echo '</ul>';
}
}
A little explanation is in order…
The function has been written with “custom loops” as well as the standard WordPress Loop in mind. It can be used when you define your own loop with the WP_Query object, as well as on normal templates that use the have_posts() construct. So, for custom loops built using the instructions in the last linked article, pass $recentPosts (or whatever you call your custom loop query object) as the first parameter. On normal loop templates, pass $wp_query. In either case, this query object contains some very useful info (like max_num_pages) that really help keep the above code simple.
I’ll leave the second parameter up to you to construct. It just has to be the basic URL of the listing page, onto which pagination stuff will be appended. It should include the trailing slash.
I’ve also included the query string in the right place, which should make this function work for pagination on WordPress search results. One oddity in this respect is that when you have something other than the front page of your site as your main post listing page (on this site it’s UPDATE 8/10/10: Whatever was causing this oddity seems to have vanished in a recent WP version. Now, just pass /blog/), the paging URLs don’t seem to work. So /blog/page/2/ just returns a 404. I’ve fudged around this by setting the $baseURL parameter of the call to this function on the blog to just / (the root). It kind of works. Anyone know why including the page slug doesn’t work?$baseURL as normal. I’ve also updated the above code to default $baseURL to the site root.
Well, the rest should be self-explanatory. Again, as with many of my WordPress tips here, this is aimed at theme developers who know their way around WP and PHP a bit. If you’re not quite there yet, maybe try the plugin I linked to at the start of this post…
Oh, as an added bonus, the CSS I use for the pagination list!
ul.paging { list-style: none; padding: 0; font-weight: bold; }
ul.paging li { float: left; margin: 0 6px 6px 0; }
ul.paging li a, ul.paging li.active { display: block; padding: 3px 6px; background-color: #f5f5f5; border: 1px solid #ccc; }
ul.paging li.active { background-color: #000; border-color: #000; color: #fff; }
Welcome! I build websites - mostly based on the brilliant, free & open 
Patternhead (9th July 2009)
This looks really useful.
Thanks for sharing :)
WP Tim (11th July 2009)
Please post the where this function is called or how to incorporate in a page. Thanks!
Steve Taylor (11th July 2009)
Tim, you would just call the function where you want the pagination controls. The basic call (say, after The Loop in
index.php) would be:pagination( $wp_query, "/" );If often include one before The Loop too, but set to only appear if not on the first page:
if ( $paged ) slt_pagination( $wp_query, "/" );For
archive.php, you’ll probably have to set up the$baseURLparameter dynamically, depending on the type of archive being shown. (Hint: the WP functionsget_category_link()andget_month_link()help out a lot!)If you’re not following, then it’s possible that a plugin might be your cup of tea. For the most part I’m addressing theme developers here.
Good luck!
sean (24th August 2009)
Hello, I’m trying to improve my search.php page with your code. No more than 5 posts should be displayed per page.
Here’s the code before yours was added:
<a href="" title=""></a>Brand: <!-- End of Byline Containing Div -->
<a href="" title="">more...</a>
Here’s how I’ve added yours:
query_vars["paged"];
if ( !$page ) $page = 1;
$qs = $_SERVER["QUERY_STRING"] ? "?".$_SERVER["QUERY_STRING"] : "";
// Only necessary if there's more posts than posts-per-page
if ( $query->found_posts > $query->query_vars["posts_per_page"] ) {
echo '';
// Previous link?
if ( $page > 1 ) {
echo '<a href="'.$baseURL.'page/'.($page-1).'/'.$qs.'" rel="nofollow">« previous</a>';
}
// Loop through pages
for ( $i=1; $i max_num_pages; $i++ ) {
// Current page or linked page?
if ( $i == $page ) {
echo ''.$i.'';
} else {
echo '<a href="'.$baseURL.'page/'.$i.'/'.$qs.'" rel="nofollow">'.$i.'</a>';
}
}
// Next link?
if ( $page max_num_pages ) {
echo '<a href="'.$baseURL.'page/'.($page+1).'/'.$qs.'" rel="nofollow">next »</a>';
}
echo '';
}
} ?>
<a href="" title=""></a>
Brand: <!-- End of Byline Containing Div -->
<a href="" title="">more...</a>
No Results Found
Please try your search again using different keywords.
This is my first attempt at pagination, but I’ve used WordPress for 5-6 projects now.
Steve Taylor (24th August 2009)
Hi Sean, from the code you posted it’s not really clear what your issue is. Could you be more specific as to what the issue is? (Please don’t post more code unless necessary, it needed a lot of tidying up!)
If you don’t understand the code enough to explain what the problem is, you might be better off with a plugin – check out the link at the top of this post.
Valid Information (11th November 2009)
Looks complicated but very useful information
ayman (9th January 2010)
how can i limit number of pages that displayed ?not all pages
Steve Taylor (9th January 2010)
Hi Ayman, you mean the number of total pages? Or to abbreviate the pagination numbers when there’s a lot, like this?
« previous 1 2 3 4 ... 23 24 25 next »Abbreviating the pagination numbers is certainly something I’ll try and get round to one day – should be pretty easy. Maybe one of the current pagination plugins does that?
Regarding limiting the total number of pages, these pages should help:
http://weblogtoolscollection.com/archives/2008/04/13/define-your-own-wordpress-loop-using-wp_query/
http://digwp.com/2009/12/limit-posts-without-plugin/
Pete (20th February 2010)
Works brilliantly. So simple.
Pete (20th February 2010)
Am I the only one that’s get recursive querystring addition when implementing this pagination script?
I have had to alter the make up of the href a little, but the bulk of the code is still the same.
I could really do with a little bit of help with this one.
Eg: http://website/?s=lorem&paged=2&paged=1&paged=3 this just keeps getting longer and longer dependent on how many links are clicked. Am I just going to have to write a string manipulation function to sort this out?
Steve Taylor (21st February 2010)
Pete, could you give a URL to an example where this is happening? The only thing I can guess at from your sample URL is that perhaps the script doesn’t work properly without “pretty permalinks“. I’m not sure why you wouldn’t have a pretty permalink structure, but if you’re stuck with “ugly” query string-based links—well, it should be easy to adapt. Do post your solution if you need to add anything.
Steven Wilson (4th March 2010)
Work a treat !! .. Thanks for sharing.
Peter (22nd March 2010)
ayman (9th January 2010) and Steve, to limit the number of pages displayed change
if ( $i == $page ) {echo ''.$i.'';
} else {
echo '<a href="'.$baseURL.'page/'.$i.'/'.$qs.'">'.$i.'</a>';
to
if ( $i == $page ) {echo ''.$i.'';
} elseif ($i < 10) {
echo '<a href="'.$baseURL.'page/'.$i.'/'.$qs.'">'.$i.'</a>';
P.s thanks steve you rock!
Steve Taylor (22nd March 2010)
Thanks Peter! (BTW, do use pastebin.ca for snippets, saves on formatting issues.)
Ryan (11th May 2010)
Hey Steve! First of all, great site.
Secondly, I have quick question:
If you notice on my “News” page (http://abletonlife.com/news), when you click on the “2″ at the bottom of the page, it loops back to the same page. I know I have more than 10 posts, so why isn’t it showing the other ones like on the home page?
Any help is appreciated! Thanks!
- Ryan
Steve Taylor (12th May 2010)
Ryan, glad you like the site! As to your issue, hard to tell what’s going on from the outside. However, it seems clear that the issue is probably nothing to do with this pagination code. The URL http://abletonlife.com/news/page/2 is showing the same as http://abletonlife.com/news, so WP’s paging itself isn’t working. The only thing I can spot as a possible starting point is that there’s no trailing slash on the URLs. If one is added, it gets removed. I can’t remember whether it’s a server-level thing or a WP thing, but in my experience the normal behaviour is for trailing slashes to be added if they’re missing. I wonder if the paging URL without a trailing slash isn’t being recognized by WP? If that lead goes nowhere, maybe check the WP forums. Good luck!
Nadeeshyama Talagala (4th July 2010)
This is great. However I found a way to eliminate the need of $baseUrl. You can add the following to make the $baseUrl for any category eliminating the second argument to the function.
$url = get_bloginfo('url');
$baseUrl = '';
$category_name = $query->query_vars['category_name'];
if (is_string($category_name)) {
$category_id = get_cat_ID($category_name);
if (isset($category_id)) {
$category_link = get_category_link($category_id);
if (is_string($category_link)) {
$baseUrl = $category_link . '/';
}
}
}
Steve Taylor (4th July 2010)
Thanks Nadeeshyama. I still find $baseURL useful for when you’re outputting posts in a loop on some custom page separate from the main blog, e.g. /news/. This is usually when I’ve fudged different post “types” using categories, though of course WP 3.0 custom post types will make this kind of thing easier, and maybe $baseURL becomes even more relevant?
Vassilis Mastorostergios (12th August 2010)
Hi, to anyone having problems with WordPress pagination (ie /page/2/ is shown exactly as the first page) try this:
add to whatever query you’re having .’&paged=’.$paged and it should work
Maja (19th August 2010)
Vassilis that is exactly what i need (i have the pge 2 problem), but i’m no good with php :( can you please be more specific where should i put that code?
thanks!
Steve Taylor (19th August 2010)
Maja, I think Vassilis is talking about queries done using the WordPress functions like
get_postsorquery_posts. Check the Codex. See also this post.Emil (29th August 2010)
This cannot be any easier, really. Simply add
where you want the pagination to show and you’re all set. This is after you paste the code Steve provided for your functions.php file.Just make sure you copy the codes from plain text instead copying to clipboard.
Great job Steve, I appreciate the work,
Emil
PS Works with 3.0.1 as well.
Emil (29th August 2010)
Sorry the php code did not show http://pastebin.com/3s8d8CY6 here is this instead :-)
Dan (10th September 2010)
Thanks for the code.
I also don’t like adding lots of plugins. This is a great way to achieve the target in a simple mod in the template
Benny (11th September 2010)
Thanks Steve! You just made my night!
skinofstars (12th September 2010)
Thank you. So much tidier than using a plugin. Works just as well in wp3.0.1. Good stuff.
Also thanks to Nadeeshyama Talagala above for doing the category $baseURL code.
Ben (17th September 2010)
Hi,
Absolutely love this bit of code because I detest unnecessary plugins. So thanks Steve for this.
Just wondering if anyone had figured out a way of doing the pagination when there are a lot of pages like:
Had a go myself but I am not much of a coder so got nowhere fast! Any help or a mod would be very much appreciated. Say limit it to the first 5 page links and then the very last page?
Steve Taylor (17th September 2010)
Hi Ben, this is on my “to do, but might not get done forever unless a project needs it” list I’m afraid! If anyone comes up with anything, do post…
James (5th October 2010)
Hi,
Nice function..Can I ask how I would implement it for Paginate Comments ?
Thanks
Steve Taylor (6th October 2010)
James, I’ve never dealt with paginated comments so I’m not sure about this. As with the above code for pages, though, I’m sure there’s a plugin somewhere to do the same thing…
Matt P (8th October 2010)
Have you figured out a way to get pagination working with “pretty permalinks”? I noticed you have a similar structure as mine “website.com/blog/article”. Noticed your pagination under “blog” passed you back to your main page. I just get a 404 error on mine. Any ideas?
Steve Taylor (8th October 2010)
How embarrassing, my code not working on my own site! :-| As you’ll see, I’ve updated my explanation of this in the post. I’m not sure, but I imagine something must have changed in a recent WP upgrade which means that now, if your main posts page is
/blog/(as it is here), you need to pass that instead of just/as the$baseURLparameter. Of course this is as it should be. A case of a fixed bug breaking a workaround… Let me know if you see exactly what’s happened.Jewel (13th October 2010)
Do you know how to paginate a custom loop?
Here is my query post:
query_posts(‘paged=’ . $paged . ‘&cat=’ . $categori .’&year=’ . $year .’&w=’ .$week );
I would like to paginate it by week. so that the viewer can navigate list of posts by pressing “next week” & “previous week” button.
Thank you,
Jewel
Steve Taylor (13th October 2010)
Hi Jewel, the above code works fine with custom loops using
query_posts. As for standard loops, just pass$wp_queryto the pagination function, as described.I’ve not done pagination by week, or by anything other than a number of posts per page, sorry.
schiz (25th October 2010)
Hey Steve,
Your code helped me a lot, however you should change $baseURL from just “/” to get_bloginfo(‘wpurl’) and then add a slash to the code. My blog was situated at domain-name.com/blog-name/ and by using “/” it tried searching on domain-name.com.
Steve Taylor (25th October 2010)
Schiz, you’re right, thanks. I always install WP in the domain root, but I guess not everyone does. However, I’ve gone for
get_bloginfo( $url )instead ofget_bloginfo( $wpurl )—I think the former is for the front-end.Prakash (30th October 2010)
hey steve,
iam using chruch child theme of genesis in my blog . i try to implement the pagination in index page but it doesn’t work and i used alumni spotlight as category to display post at most 5 in each page . when i shows http://ptracker.com/evertrueHBS/?paged=2 this page also display like as http://ptracker.com/evertrueHBS that page.. give me solution
Steve Taylor (31st October 2010)
Hi Prakash, I don’t know whether there’s anything in the theme you’re using that might conflict with this, but it shouldn’t. The example URLs you gave seem to be fine as far as they go, but I don’t see the pagination code there, so it’s hard to know what’s going wrong. Just make sure you pass the right query object to the function. If you’re not sure what this is about, maybe you’d be better using one of the many pagination plugins out there?
Prakash (1st November 2010)
Hi steve, Thanks for your reply. In that page http://ptracker.com/evertrueHBS i cant identify where it is to pass query object to the function because its completely based on hooks type and we used widget to display the category post on index page.. did u see the pagination that bottom of the index page? its automatically displayed with help of function. for your ref http://www.studiopress.com/demo/church.html this concern developed this theme and also gave the demo on that website thank you
Steve Taylor (1st November 2010)
Hi Prakash, I’m very sorry but it’s hard to understand exactly what your problem is. Maybe you could post some code (best to use something like pastebin.ca and link to it).
Prakash (1st November 2010)
//my home page of this theme
<script type="text/javascript" src="/themes/church/cufon-yui.js”>
<script type="text/javascript" src="/themes/church/Diavlo_Light_300.font.js”>
Cufon.replace(‘h4.widgettitle’, { fontFamily: ‘Diavlo Light’ });
Cufon.replace(‘div.widgetwrap h2 a’, { fontFamily: ‘Diavlo Light’ });
Widgets screen. There you can drag the Genesis – Featured Posts widget into the Featured Top Left widget area on the right hand side. To get the image to display, simply upload an image through the media uploader on the edit page screen and publish your page. The Featured Posts widget will know to display the post image as long as you select that option in the widget interface.”, ‘genesis’); ?>
Widgets screen. There you can drag the Genesis – Featured Posts widget into the Featured Top Right widget area on the right hand side. To get the image to display, simply upload an image through the media uploader on the edit page screen and publish your page. The Featured Posts widget will know to display the post image as long as you select that option in the widget interface.”, ‘genesis’); ?>
Widgets screen. There you can drag the Genesis – Featured Posts widget into the Featured Bottom widget area on the right hand side. To get the image to display, simply upload an image through the media uploader on the edit page screen and publish your page. The Featured Posts widget will know to display the post image as long as you select that option in the widget interface.”, ‘genesis’); ?>
Prakash (1st November 2010)
hey steve, thanks once again for your reply, i send home page code to you. give me solution
Steve Taylor (1st November 2010)
Sorry Prakash, I’m going to have to give up on this. The code you’ve posted is totally irrelevant and “give me a solution” is a bit rude when I’m trying to help you for nothing. Best of luck!
WP_user (23rd November 2010)
Thanks, good function.
With my little modification, it now shows links on my site in this way:
« previous 1 … 4 5 [6] 7 8 … 42 next »
Steve Taylor (23rd November 2010)
That’s great. Could you post / link to your modification?
WP_user (24th November 2010)
here it is:
function pagination($first=1,$last=1,$middle=5,$baseURL=false,$wp_query=false ) { if(!$baseURL) $baseURL= get_bloginfo('url'); if(!$wp_query)global $wp_query; $page = $wp_query->query_vars["paged"]; if ( !$page ) $page = 1; $qs = $_SERVER["QUERY_STRING"] ? "?".$_SERVER["QUERY_STRING"] : ""; if ( $wp_query->found_posts > $wp_query->query_vars["posts_per_page"] ) {// Only necessary if there's more posts than posts-per-page echo '<ul class="paging">'; if ( $page > 1 ) { // Previous link? echo '<li class="previous"><a href="'.$baseURL.(($page==2)?('page/'.($page-1).'/'):'').$qs.'">« Previous</a></li>'; } $dots=false; for ( $i=1; $i <= $wp_query->max_num_pages; $i++ ){ // Loop through pages if($i<=$first || $i<=$middle && $page<$middle || $i>$wp_query->max_num_pages-$last || $i>$wp_query->max_num_pages-$middle && $page>$wp_query->max_num_pages-$middle+1 || $i>$page-ceil($middle/2) && $i<=$page+floor($middle/2)){ if ( $i == $page ) { // Current page or linked page? echo '<li class="active">'.$i.'</li>'; } else { echo '<li><a href="'.$baseURL.(($i!=1)?('page/'.$i.'/'):'').$qs.'">'.$i.'</a></li>'; } $dots=false; }elseif(!$dots){ echo '<li class="dots">...</li>'; $dots=true; } } if ( $page < $wp_query->max_num_pages ) { // Next link? echo '<li><a href="'.$baseURL.'page/'.($page+1).'/'.$qs.'">Next »</a></li>'; } echo '</ul>'; } }Justin W Hall (5th April 2011)
A little late to the party here but thanks for code snippet. command + C & command + V was a tough one but I managed. I did have to modify your CSS for color coordination. In the future I’ll expect a little more effort on your behalf ;)
Thanks again.
P.S. – Are still using the script?
Steve Taylor (5th April 2011)
Hi Justin, glad you coped – I do leave most of the burden for my readers ;)
Yeah, I still use it as a default, though more often these days clients are going for a Facebook-style AJAX “more” button.
Justin W Hall (5th April 2011)
Well, It’s been filed nicely away in my code snippets. I’ll now waiting for AJAX solution ;)
Thanks again.
Sandip (1st May 2011)
Hi i use wordpress for this and i want to display pagination at front side without reloaded page.
Steve Taylor (1st May 2011)
Hi, could you put long bits of code on pastebin.ca, and be more specific with your question? Sounds like you need an AJAX version of this script, which I don’t have at the moment.
Jonny (5th May 2011)
Nice piece of code iron out a few issues and it could become a very useful function
$wp_query is globally available, i might be wrong but i can’t think of any situation where you’d need to pass the query.
I don’t know if this cased the earlier issue but default values for arguments can’t be functions, they have to be constants in php, i’m confused at how this worked at all as that usually throws a fatal error.
The function won’t work with default permalinks.
Steve Taylor (6th May 2011)
@Jonny, thanks for the heads-up on the default argument, I’ve corrected it. My own version of this has changed a lot for my needs, I just added that blindly on the advice of a previous commenter.
I’ve had situations where I need to pass a custom loop query, so that facility is there if needed. Just pass
$wp_queryif you want.David H (15th May 2011)
Hey Steve, you are probably so tired of responding to this thread by now….
I am wondering, of course, if there is an expanded way to paginate now that things like Jquery Tabs are popular on the home page of various WordPress themes.
For instance, in a classified ads theme which also uses some modified wp code to paginate, there is a default index page Tab display of various queries.
Tab one might be a query run for the “Latest Ads”–if the query is set for, say, 30 ads, then this tab will line up the short “posts” of ads and show “Page 1 of 3″ at the bottom of that tab view. If I click on the number 2 the link will be “/page/2/” and the next set of listings appears inside the same tab.
However, the PROBLEM starts when I click Tab Two—–If Tab 2 “Featured Listings” (using “sticky”) is clicked then I see the listings (that are all marked “sticky”) and at the bottom of the tab I may see “Page 1 of 4″. But to click, say, number 2 will produce the url “/page/2″ again–the same url as in Tab One.
On clicking “2″ in the “Featured Listings” Tab the resulting listings will now be thrown back to the Tab one view and I will be looking at the Tab One “Just Listed” second page of listings.
Some people have said that only an Ajaxed version can help create separate Tabs pagination that is correct for the query that produces those types of listings.
I am thinking that there must be a function that could run through the queries in the Tabs block of code and produce at one time the Complete list of “/page/1….infinity/”, accumulating all of the paginations for 2 or 3 tabs of separate queries, whether by iterating “/page_just_listed/3/” and “/page_featured/4/”, or by creating , or,
just creating the Total pagination in one string for all three tabs in a way that while we are in Tab two the pagination stays in the Tab two view while “/page/12/” is being served.
It is the jquery Tabs invention that creates a need for a pagination that matches its needs.
Steve, can you think of a way to do this without Ajax?
Thank you for your consideration!
Steve Taylor (15th May 2011)
David, I’ve used jQuery tabs but not for this kind of thing. I can’t really grasp the issue here without setting the whole thing up and I’m working to a tight deadline at the moment. Maybe try the jQuery Tools forum or the wp-hackers list? Good luck!
Danilo (11th June 2011)
Hello Steve, I wanted to say thank you for the function you shared with us.
I’ve found in very useful and decided to improve it a little.
Now it shows just a range of pages before and after the actual one and also 2 links, one for the first and one for the last page available, but only when the current page is not too close to one of them.
I’ve made it work both if the site uses “pretty permalinks” or the standard permalinks structure.
I’ve pasted the function, together with a small helper function on pastebin, just in case you were curious and wanted to give it a look..
I hope this is useful to others as your one was useful to me..
bye ;)
Steve Taylor (12th June 2011)
Danilo, many thanks for posting this. All my work is project-driven at the moment, so maybe one day a project will demand better pagination and I’ll improve my code!
Duxx (21st June 2011)
For me its not working, shows the page links but when i click on it nothing happens
Steve Taylor (21st June 2011)
Hi Duxx, any more details? Maybe this will help: http://sltaylor.co.uk/blog/solving-wordpress-problems/
Duxx (21st June 2011)
Thank you Steve Taylor :)