Customizing the Posts Per Page in WordPress

Posted in Tutorials

Tweet This Share on Facebook Bookmark on Delicious Digg this Submit to Reddit

In the blog index page, you can set the number of posts per page in “WordPress Dashboard -> Settings -> Reading” and set “Blog post to show at most __ posts” .  There will be pagination links to navigate to the older pages.

However, this setting not only affects the posts per page for the blog index, but also for the blog archives.  Suppose you want the main blog index to show 10 posts per page and the category archives to show 2 posts per page.  How would you do that?

In our example (using WordPress 3.8.1), we will set the 10 posts in “WordPress Dashboard -> Settings -> Reading” for the blog index page.  And we will customize the category archive page to show 20 posts per page.

Using the pre_get_posts hook to customize posts per page

We will use the pre_get_posts hook in the functions.php file.  Here is how to edit the functions.php file.

Add the following to the functions.php file …

add_action('pre_get_posts', 'limit_posts_per_archive_page');

The pre_get_posts hook is a WordPress hook that is called right before the loop query takes place.  Hence it is our opportunity to alter the query variables before querying the database.   The second parameter in add_filter is your arbitrarily named function for us to perform that variable alteration.

Next we define the function limit_posts_per_archive_page in the functions.php file like so …

function limit_posts_per_archive_page($query) {
   if ( is_archive() ) {
      $query->set( 'posts_per_page', 20 );

If you print_r the $query object within limit_posts_per_archive_page, you see the [query_vars] array of other variables that you can alter.

Using the pre_option_posts_per_page hook to customize posts per page

Alternatively, you can use pre_option_posts_per_page hook …

add_filter('pre_option_posts_per_page', 'limit_posts_per_archive_page');
function limit_posts_per_archive_page( $posts_per_page ) { 
 global $wp_query;
 if ( $wp_query->query_vars['category_name']=='examples') {
   return 20;
 return $posts_per_page;

Inside our function, we access the $wp_query object.  And if it shows that the archive category has a slug of “examples”, then we return 20 for the $posts_per_page.  Otherwise, we return the original $posts_per_page.

WordPress has other similar hooks as explained in the Codex.  This is a technique where you can custom alter the WordPress options that are set in the dashboard.   To see all the variables that you can alter, call these …

$tempdebug = get_alloptions();

in our hook function.  For example, if you need to customize posts_per_rss option, use this hook:  pre_option_posts_per_rss.