WordPress Pagination with  paginate_links()

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 https://developer.wordpress.org/reference/classes/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()
    // https://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.