There are a more than a few ways to setup WordPress pagination, or “paged” links, in a WordPress theme. One popular method involves using the WP-PageNavi plugin. This plugin is great for someone non-technical who wants to add pagination onto their current WordPress site, however it’s not an ideal option for a theme developer.

Jacob Gold at 10Up wrote a great article on Smashing Magazine that discusses using a lesser-known WordPress function to handle the heavy lifting. The paginate_links() function makes it’s incredibly simple to add pagination to your WordPress themes. Here’s how I typically use it.

The PHP

/**
 * Pagination for archive, taxonomy, category, tag and search results pages
 *
 * @global $wp_query http://codex.wordpress.org/Class_Reference/WP_Query
 * @return Prints the HTML for the pagination if a template is $paged
 */
function base_pagination() {
    global $wp_query;

    $big = 999999999; // This needs to be an unlikely integer

    // For more options and info view the docs for paginate_links()
    // http://codex.wordpress.org/Function_Reference/paginate_links
    $paginate_links = paginate_links( array(
        'base' => str_replace( $big, '%#%', get_pagenum_link($big) ),
        'current' => max( 1, get_query_var('paged') ),
        'total' => $wp_query->max_num_pages,
        'mid_size' => 5
    ) );

    // Display the pagination if more than one page is found
    if ( $paginate_links ) {
        echo '<div class="pagination">';
        echo $paginate_links;
        echo '</div><!--// end .pagination -->';
    }
}

Once you’ve added this to the functions.php file you can use the base_pagination() function wherever you would like the pagination to display in your theme. This could be taxonomy.php, archive.php, category.php, index.php or any listing based archive template used in WordPress.

Here’s a basic example of how I use this in my base development starter theme.

Markup for a Theme

<?php if ( have_posts() ) : while ( have_posts() ) : the_post(); ?>

<div <?php post_class('clearfix'); ?> id="post-<?php the_ID(); ?>">
    <?php if ( has_post_thumbnail() ): ?>
    <div class="entry-thumbnail">
        <?php the_post_thumbnail('listing'); ?>
    </div>
    <?php endif; ?>

    <div class="entry-content">
        <h2 class="post-title"><a href="<?php the_permalink() ?>" rel="bookmark"><?php the_title(); ?></a></h2>
        <p class="post-meta">Posted by <?php the_author_posts_link(); ?> on <?php the_time(get_option('date_format')); ?></p>
        <div class="entry clearfix">
            <?php the_excerpt();?>
        </div>
    </div><!--// end .entry-content -->
</div><!--// end #post-<?php the_ID(); ?> -->

<?php endwhile; ?>

<?php if ( function_exists('base_pagination') ) { base_pagination(); } else if ( is_paged() ) { ?>
<div class="navigation clearfix">
    <div class="alignleft"><?php next_posts_link('&laquo; Previous Entries') ?></div>
    <div class="alignright"><?php previous_posts_link('Next Entries &raquo;') ?></div>
</div>
<?php } ?>

<?php else : ?>

<h2 class="post-title">Sorry, no posts have been found.</h2>
<div class="entry">
    <p>No posts have been found...</p>
</div>

<?php endif; ?>

CSS Styles

Here’s a snippet of CSS I commonly use to style the pagination elements.

/** Pagination */
.pagination {
    background:#E7E6E5;
    background:rgba(255,255,255,0.35);
    padding:7px 10px 5px;
    -webkit-border-radius:5px;
    -moz-border-radius:5px;
    border-radius:5px;
}
.pagination .page-numbers {
    padding:3px 6px;
    font-size:15px;
    font-weight:bold;
}
.pagination .current {
    color:#000;
}

Hopefully this help’s you quickly add pagination in your WordPress theme. Please let me know if you have any questions, issues or suggestions in the comments below.

About the Author

Kevin Leary is a web developer in Boston, MA specializing in enterprise website design and development, online marketing, and conversion optimization.