Modify the WordPress Pagination

The code snippet below demonstrates how to modify the WordPress pagination to customize its appearance and behavior:

function wpsnippets_custom_pagination() {
    global $wp_query;

    $big = 999999999; // A large number to ensure pagination works with any number of posts

    echo paginate_links(array(
        'base' => str_replace($big, '%#%', esc_url(get_pagenum_link($big))),
        'format' => '?paged=%#%',
        'current' => max(1, get_query_var('paged')),
        'total' => $wp_query->max_num_pages,
        'prev_text' => __('Previous'),
        'next_text' => __('Next'),
    ));
}

This code snippet creates a custom pagination function wpsnippets_custom_pagination() that can be used to display pagination links on any WordPress page. It uses the paginate_links() function provided by WordPress to generate the pagination HTML.

To use this code snippet, simply call the wpsnippets_custom_pagination() function wherever you want to display the pagination links. The function will automatically generate the pagination links based on the current query.

The paginate_links() function accepts an array of parameters to customize the pagination. In the example above, we set the base parameter to replace a placeholder with the actual page number in the URL. We also set the format parameter to specify the URL format for the pagination links.

Additionally, we set the current parameter to determine the current page number, the total parameter to specify the total number of pages, and the prev_text and next_text parameters to define the text for the previous and next links.

This code snippet is useful when you want to have more control over the appearance and behavior of the pagination links in your WordPress theme. It allows you to easily customize the pagination to match your design requirements.

Examples

Example 1: Customizing the Pagination Markup

This use case demonstrates how to modify the markup of the WordPress pagination to match a specific design or layout.

function wpsnippets_custom_pagination_markup() {
    global $wp_query;

    $big = 999999999; // need an unlikely integer

    $paginate_links = paginate_links( array(
        'base'      => str_replace( $big, '%#%', esc_url( get_pagenum_link( $big ) ) ),
        'format'    => '?paged=%#%',
        'current'   => max( 1, get_query_var('paged') ),
        'total'     => $wp_query->max_num_pages,
        'prev_text' => __('Previous'),
        'next_text' => __('Next'),
    ) );

    // Custom markup
    $paginate_links = str_replace( "<ul class='page-numbers'>", "<ul class='pagination'>", $paginate_links );
    $paginate_links = str_replace( "<li>", "<li class='page-item'>", $paginate_links );
    $paginate_links = str_replace( "<a", "<a class='page-link'", $paginate_links );

    echo $paginate_links;
}

This code example demonstrates how to customize the markup of the WordPress pagination by modifying the output generated by the paginate_links() function. It replaces the default <ul> and <li> elements with Bootstrap-compatible classes for styling purposes.

Example 2: Adding Custom Pagination Parameters

This use case demonstrates how to add custom parameters to the WordPress pagination, such as additional query string parameters or custom URL structure.

function wpsnippets_custom_pagination_parameters() {
    global $wp_query;

    $paginate_links = paginate_links( array(
        'base'      => add_query_arg( 'custom_param', 'value', get_pagenum_link( 999999999 ) ),
        'format'    => '?paged=%#%',
        'current'   => max( 1, get_query_var('paged') ),
        'total'     => $wp_query->max_num_pages,
        'prev_text' => __('Previous'),
        'next_text' => __('Next'),
    ) );

    echo $paginate_links;
}

This code example demonstrates how to add custom parameters to the WordPress pagination by using the add_query_arg() function. In this example, a custom parameter named custom_param with a value of value is added to each pagination link.

Example 3: Customizing the Pagination Labels

This use case demonstrates how to customize the labels used in the WordPress pagination, such as the “Previous” and “Next” links.

function wpsnippets_custom_pagination_labels() {
    global $wp_query;

    $paginate_links = paginate_links( array(
        'base'      => str_replace( 999999999, '%#%', esc_url( get_pagenum_link( 999999999 ) ) ),
        'format'    => '?paged=%#%',
        'current'   => max( 1, get_query_var('paged') ),
        'total'     => $wp_query->max_num_pages,
        'prev_text' => __('Previous Page'),
        'next_text' => __('Next Page'),
    ) );

    echo $paginate_links;
}

This code example demonstrates how to customize the labels used in the WordPress pagination by modifying the prev_text and next_text parameters of the paginate_links() function. In this example, the labels are changed to “Previous Page” and “Next Page” respectively.