How to Add Numeric Pagination to Your WordPress Site
After running a WordPress blog for a while, the number of created posts tends to be too large to manage and fit onto a single page. Thus, webmasters have to think of ways of incorporating pagination into blogs, categories, tags, and archive pages to counteract this issue. Of course, doing so comes with clear benefits. Posts are displayed in batches, which puts less stress on the server and results in faster page load times than displaying all the posts at once. Furthermore, it makes your blog easily accessible for crawlers and more usable for regular visitors looking for a certain piece of information, especially if paired with a search feature.
Apart from that, pagination can also be used to break up long posts, pages or comment threads into several parts, making them easier to read. Therefore, it is no surprise that most WordPress themes come with some form of pagination. WordPress users whose theme doesn’t offer that functionality or does, but one which doesn’t fit the design of their website, will find this article useful. In it, we will explain how to add numeric pagination to your WordPress website, the most commonly used pagination type.
Without further ado, let us begin. Here’s what we will be covering:
Blog & Magazine Themes
View Collection
As WordPress offers an abundance of plugins, it is easy to find one for nearly any purpose by simply searching through the repository on WordPress.org. This holds true for adding any kind of pagination to a WordPress website. We had no issue finding several pagination plugins, but the one we will showcase is called Pagination.
The Pagination by BestWebSoft is a freemium plugin used to add customizable numeric pagination to your pages, blog, archives, search results, authors, categories, and tags. It comes with a set of beginner-friendly settings for the position of the pagination, its parts, and design, while also providing a way to hide the existing theme-specific pagination if you choose not to use it. And, while most of the options are self-explanatory, its documentation will help you resolve any doubts regarding the options and their use.
Finally, the plugin allows more advanced WordPress users to add custom code to further adjust the pagination, as well as display it in custom locations using suitable code snippets. The premium version comes with multiple pagination options, compatibility with the Divi theme, and premium support. However, in this article, we will only be covering the free version.
After installing and activating the plugin, navigate to Pagination > Settings, which will take you to the Settings tab, where most of the configuration options are. The options are divided into three sections: General, Numeric Pagination, and Custom Styles, with the premium options being highlighted with a different color and inaccessible unless you upgrade.
The configuration process starts with the General tab, where you can choose where you wish to display the pagination created by this plugin and where you wish to hide the existing pagination provided by your theme. The plugin hides the standard, theme-provided pagination by using CSS code with standard CSS classes as the relevant selectors. This option will work for most WordPress themes which use the same CSS classes.
However, there is an additional option for themes which don’t use those classes. More precisely, you can tick the checkbox next to the Hide Custom Pagination option and add one or more CSS selectors behind the custom pagination found on your website. For this section of the article, we didn’t need to use it, as the theme we are using, called Lekker, uses standardized CSS classes. However, this option can be an asset nevertheless. And, to properly use it, you will need to know how to inspect your website using developer tools, as well as a basic understanding of HTML and CSS code. For those unfamiliar with these concepts, we advise reading the section on hiding theme pagination at the end of the article.
In the next section, you can choose the position of the new pagination, whether you wish to enable the “Page … of …” label, as well as the Prev/Next links. For those links, you can also specify the labels, with “<< Previous” and “Next >>” being the default values. Furthermore, you can set up the page range, i.e. the number of page links that are shown before and after the current page number when the pagination is displayed on the website.
Finally, we must point out that if you choose the “Custom function position” as the value of the Pagination Position option, you should take a look at the Pagination subsection next to the main tabbed section which we are currently using. In this section, you are given suggestions of how to display the pagination in some custom locations (posts, multipage, and comments) using related code snippets. But, as we haven’t used a custom pagination position for this article, we will not discuss these settings further.
Having said that, let us proceed to the final configuration section called Custom Styles. To enable it, the checkbox next to the Custom Pagination Style option must be ticked. Then, you can set up various design options provided by this plugin. For the most part, we have used the default values, except for the pagination block width, but you can set the options as you see fit.
We would like to clarify that these options only apply to the pagination section and its page links and labels: they aren’t used for styling the various aspects of the pages where the pagination is displayed, as some of the option names might suggest. Having said that, after configuring the options within this section, click the “Save Changes” button to save all the option choices you have previously made.
The plugin also offers other helpful options which we mustn’t fail to mention. These include a way to reset all the option choices back to their default values as well as to insert CSS, PHP, and JS code. The former is achieved using the Default Settings option within the Misc tab, while the latter is achieved by adding the corresponding code within the suitable code subsections found in the Custom Code tab.
Finally, if you have any doubts regarding the plugin options, you can always access the plugin documentation by clicking the “Read the instruction” link which is found near the top of your screen, while within any of the tabs of the Pagination > Settings section.
This concludes our overview of the plugin. The only thing that remains is to review the resulting pagination achieved by it. It is shown below.
Apart from using a plugin, you can add numeric pagination to your WordPress website using custom code. This method is, generally speaking, more appealing to intermediate and advanced WordPress users, as it comes with a prerequisite of having a considerable coding experience and overall WordPress knowledge. Nevertheless, it offers a way to implement the pagination exactly as you want it, without the use of any additional WordPress plugins which might slow down your website. We will cover it in this article, and let you decide which method is more appropriate for your website.
There are a couple of things we must mention before delving into code. First, as a precautionary measure, we strongly suggest making a backup of your website before proceeding. And, as you will need to insert the code via FTP, we suggest brushing up on your knowledge of FTP. Having done both, proceed below.
For this article, we have created a simple PHP code snippet which will allow you to display numeric pagination on the blog page, search page, and archives, including categories, tags, author, and date archive pages. The code is given below.
function qodef_custom_pagination() {
global $wp_query;
if ( get_query_var( 'paged' ) ) {
$paged = get_query_var( 'paged' );
} elseif ( get_query_var( 'page' ) ) {
$paged = get_query_var( 'page' );
} else {
$paged = 1;
}
if ( is_front_page() || is_home() || is_archive() || is_search() ) { ?>
<div class="qodef-custom-pagination">
<?php echo paginate_links( array(
'base' => str_replace( 999999999, '%#%', esc_url( get_pagenum_link( 999999999 ) ) ),
'total' => $wp_query->max_num_pages,
'current' => $paged,
'prev_text' => '<span aria-label="' . esc_attr__( 'Previous page', 'textdomain' ) . '">' . esc_html__( '«', 'textdomain' ) . '</span>',
'next_text' => '<span aria-label="' . esc_attr__( 'Next page', 'textdomain' ) . '">' . esc_html__( '»', 'textdomain' ) . '</span>'
) ); ?>
</div>
<?php }
}
Let us now explain it.
The code represents a function called qodef_custom_pagination() that we created for displaying numeric pagination. This is achieved by calling the paginate_links() function in the code. Even though this function accepts a large variety of arguments, we have only used very few. These are the base of the pagination URL, the total number of pagination pages, the current pagination page, and the prev/next text labels.
Specifically, we have used the get_pagenum_link() function for the pagination URL, the max_num_pages property of the global WP_Query object for the total number of pages, the get_query_var() function to get the current pagination page, and have specified the whole HTML structure of the prev/next links, which are represented as left and right arrow, respectively.
Additionally, we have wrapped the code with an <div> element that has a CSS class of qodef-custom-pagination. This CSS class will be used for creating the code needed for the style of our custom pagination later.
Finally, the code is wrapped again with an if statement, to ensure that the code is executed only if certain conditions are met. More precisely, the pagination will be created only on the following pages: static homepage, blog page, search page, and archives, i.e. author pages, date pages, categories, and tags. And, since the code relies on the global instance of a WP_Query object, it will not work for any custom queries, i.e. for custom post type pages, their archives, and taxonomy pages. Meaning, the pagination will be displayed similarly to how it was done using the plugin mentioned above.
This concludes our explanation of the code. However, for it to work properly, there are some additional things we must carefully elaborate on. These are where the code should be placed and how it should be called, i.e. executed.
Firstly, as our qodef_custom_pagination() function represents a PHP coding snippet, it should be added either to the functions.php file of your child theme or a site-specific plugin, via FTP. However, we will not go into details of how such code is added via FTP in this article. Instead, we will focus on the second aspect that is needed, i.e. its execution.
Specifically, for a custom function to work on a WordPress website, it needs to be executed in one of two ways: directly inserting the function call in the appropriate template file or by hooking the function onto an appropriate hook. Let us briefly go over both.
The first method is the same as was suggested by the plugin we used in our previous section. More precisely, it involves inserting a similar code snippet inside a suitable template file via FTP.
if( function_exists( 'custom-function-name' ) ) custom-function-name(…);
This small pseudo-code snippet represents a simple way of calling a custom function, as long as it was previously defined. Of course, the custom-function-name part needs to be replaced with the relevant function name in both cases, while the three dots should be replaced with a parameter or an array of parameters which the function accepts, or removed if the custom function doesn’t accept any parameters.
As an example, the Pagination plugin we reviewed above suggested the following snippet, with the function being called pgntn_display_pagination and posts as the one parameter that is used.
if ( function_exists( 'pgntn_display_pagination' ) ) pgntn_display_pagination( 'posts' );
In our case, since the function is called qodef_custom_pagination and since it doesn’t accept any parameters, we could execute it with this additional code embedded into a suitable template file.
if( function_exists( 'qodef_custom_pagination' ) ) qodef_custom_pagination();
That suitable template file could be the index.php, page.php, single.php, search.php, or some other template file, depending on the file structure of your theme. Thus, when executing custom functions this way, you should consult the authors of your theme regarding the correct file path and code snippet placement within that file.
However, you should also know that this way of adding custom functionalities to a WordPress website is less advised in recent years as theme template files will get overridden by updates. Therefore, even though your custom function may be safely stored inside the functions.php file of your child theme or a site-specific plugin, its call that executes the function, i.e. the small snippet we previously mentioned, will need to be re-inserted inside the same template file after each theme update.
Thus, the process of maintaining the pagination, or any other custom functionality, is tiresome and difficult to keep track of. We will, therefore, also cover the second way of executing custom functions in WordPress, which is more widely accepted in recent years, despite being developer-friendly.
The second way of executing custom functions is to “hook” them onto appropriate WordPress hooks, which could be part of WordPress core files or custom-created using themes and plugins. Simply put, these hooks represent placeholders within the code that could be used to attach, i.e. hook onto, new custom functions which are created later by other developers or WordPress users.
The process of “hooking” the custom function onto an appropriate hook is the same as placing the function call into the correct place within a specific template file. This means that the function will be executed in that place as if a function call was inserted there instead. The benefit of this method is that you can keep track of all the code more easily and your customizations are safe from updates. This way, you can keep both the custom functions and the added code lines which “hook” them inside the functions.php file of your child theme or site-specific plugin, as the two suggested places for adding PHP code snippets.
That said, let us explain how it relates to the qodef_custom_pagination() function we created for this article. First, let us note that there are two types of hooks – action hooks and filter hooks. The former are used for adding new functionalities, while the latter are used for changing existing ones.
Since our custom function adds new pagination while not altering the existing pagination provided by the theme we used, that means we need to “hook” our function onto a suitable action hook. To do so, we need to use the add_action() function, which is used in the following manner:
add_action( 'suitable-action-hook-here', 'custom-function-name-here' );
Of course, you will need to replace the first parameter with a suitable action hook and the second with the name of your custom function. Similar to how it was done in the first way of executing custom functions, we advise consulting with the theme authors on finding a suitable theme-specific action hook.
For our example, we have used the lekker_action_after_page_content_holder action hook, which is specific to the Lekker theme we used, while the function name is qodef_custom_pagination, as previously mentioned. Thus, in our case, the snippet looks the following:
add_action( 'lekker_action_after_page_content_holder', 'qodef_custom_pagination' );
To use it, we needed to insert it either inside the functions.php file of our child theme or a site-specific plugin. As for the placement of this code line, it is most commonly added either directly above or directly below the function that it hooks, to keep the custom code snippets more organized. We have opted for the latter. Therefore, the complete PHP code snippet we used to display the pagination section on our website is the following:
function qodef_custom_pagination() {
global $wp_query;
if ( get_query_var( 'paged' ) ) {
$paged = get_query_var( 'paged' );
} elseif ( get_query_var( 'page' ) ) {
$paged = get_query_var( 'page' );
} else {
$paged = 1;
}
if ( is_front_page() || is_home() || is_archive() || is_search() ) { ?>
<div class="qodef-custom-pagination">
<?php echo paginate_links( array(
'base' => str_replace( 999999999, '%#%', esc_url( get_pagenum_link( 999999999 ) ) ),
'total' => $wp_query->max_num_pages,
'current' => $paged,
'prev_text' => '<span aria-label="' . esc_attr__( 'Previous page', 'textdomain' ) . '">' . esc_html__( '«', 'textdomain' ) . '</span>',
'next_text' => '<span aria-label="' . esc_attr__( 'Next page', 'textdomain' ) . '">' . esc_html__( '»', 'textdomain' ) . '</span>'
) ); ?>
</div>
<?php }
}
add_action( 'lekker_action_after_page_content_holder', 'qodef_custom_pagination' );
This has ensured that the pagination section was placed in the exact position that we wanted it to. And, if you opt for the same hook route, you need to make sure to replace the lekker_action_after_page_content_holder action hook with one specific to the theme you are using to achieve the same.
The only thing that remains now is to create the CSS code which styles it to your liking. Unfortunately, this is done on a case-by-case basis, which is why we can’t suggest any code that would appeal to all WordPress users. Instead, we will include the styling code we created for the article so that you can adjust it according to your needs and CSS knowledge. Meaning the code shouldn’t be simply copied and pasted, but expanded upon.
Having said that, the CSS code that we used for the article is given below.
.qodef-custom-pagination {
position: relative;
vertical-align: top;
background-color: #eee;
margin: 48px 0 0;
padding: 13px 0;
display: flex;
justify-content: center;
align-items: center;
}
.qodef-custom-pagination .nav-links {
position: relative;
display: flex;
align-items: center;
justify-content: center;
}
.qodef-custom-pagination .page-numbers {
position: relative;
margin: 0 7px;
padding: 0 3px;
font-size: 22px;
line-height: 32px;
}
.qodef-custom-pagination .page-numbers:first-child {
margin-left: 0;
}
.qodef-custom-pagination .page-numbers:last-child {
margin-right: 0;
}
.qodef-custom-pagination .page-numbers.next,.qodef-custom-pagination .page-numbers.prev {
padding: 0;
font-size: 30px;
}
.qodef-custom-pagination .page-numbers.prev {
margin-right: 40px;
}
.qodef-custom-pagination .page-numbers.next {
margin-left: 40px;
}
.qodef-custom-pagination .page-numbers.current, .qodef-custom-pagination .page-numbers:hover {
color: #e82a2a;
}
.qodef-custom-pagination .page-numbers.current::before,
.qodef-custom-pagination .page-numbers.current::after{
position: absolute;
content: '';
width: 15px;
height: 7px;
}
.qodef-custom-pagination .page-numbers.current::before{
left: 0;
top: 0;
border-left: 2px solid #e82a2a;
border-top: 2px solid #e82a2a;
}
.qodef-custom-pagination .page-numbers.current::after{
right: 0;
bottom: 0;
border-right: 2px solid #e82a2a;
border-bottom: 2px solid #e82a2a;
}
For the most part, the CSS code that we created for this article is rather simple, as it specifies the basic CSS rules for elements which are part of our custom pagination.The only thing that we will mention is the final part of the code. It gives the current pagination page number a custom design, created using borders of uneven length placed upon the ::before and ::after pseudo-elements.
With that being said, after you create the CSS code for your website in a similar manner, you should insert it in the Appearance > Customize > Additional CSS section or any CSS-inserting plugin you usually use. In our case, after inserting the above-mentioned code snippets, we have gotten the following result.
While in most cases our work would be done at this point, there is one final matter we will elaborate on: how to hide the pagination provided by your theme and use the custom one created using either of the methods we discussed above.
To hide the default pagination provided by your theme using CSS, inspect the pagination section using the developer tools of your current browser first. This will help you understand the HTML structure of the pagination, as well as the website page as a whole, and will help you find a suitable CSS selector.
To do so, right-click somewhere within the pagination section provided by your theme and select “Inspect”.
This will open your browser’s developer tools in the Elements tab, exactly on the element you right-clicked. From there, inspect the HTML structure of that section by hovering over the elements. As you hover over them, they will be highlighted on the screen. After you find the exact HTML element you wish to hide with CSS, look for some specific attributes which you could use as CSS selectors. In most cases, those are the CSS classes and IDs of those elements. We will explain this using the example below.
In our example, we have right-clicked on the <div> element with the CSS class of nav-links, which is highlighted on the screenshot below. If we wanted to hide that element alone, we could use .nav-links as the CSS selector, where the dot (.) means that nav-links is a CSS class.
However, in most cases, you will need to find the wrapping elements of the element you right-clicked on. This way, you can hide additional HTML elements that are part of that wrapping element or any unnecessary margin or padding added to that wrapping HTML element. In our case, the <div> element we right-clicked on is wrapped with a <nav> element which has two CSS classes – navigation and pagination.
Additionally, the <nav> element is also wrapped with a <div> element that has two CSS classes – qodef-m-pagination and qodef–wp. We can opt to hide either of these two wrapping elements. As both elements contain two CSS classes, we could target them using the .class1-name.class2-name CSS selector, for added precision. This means that, if we wanted to hide the inner wrapping element, we would use .navigation.pagination as the CSS selector, whereas if we wanted to hide the outer wrapping element, we would use .qodef-m-pagination.qodef–wp.
Having found a suitable CSS selector, you can hide that element quite easily. Users opting for the Pagination plugin can insert that CSS selector in the input field next to the Hide Custom Pagination option described above. However, you can also hide the pagination section with a simple CSS code snippet.
Here is an example of such a snippet:
your-css-selector {
display: none;
}
Of course, you will need to replace the your-css-selector part with the CSS selector you previously found inspecting the HTML structure. In our case, we have opted to hide the outer wrapping element, represented by the .qodef-m-pagination.qodef–wp as the CSS selector. We have used the following code:
.qodef-m-pagination.qodef--wp {
display: none;
}
to hide the default pagination provided by the Lekker theme that we used for this article.
After creating a similar CSS snippet for your website, insert it into the Appearance > Customize > Additional CSS section or CSS-inserting plugin, next to the previously added styling CSS code. The pagination provided by your theme will then be hidden and you can use the newly created one.
Final Thoughts
In this article, we have described two methods of adding numeric pagination to a WordPress website. Even though intended for different types of WordPress users, they share some of the same steps: choosing the appropriate pagination options, displaying the pagination section on the website using code, and adjusting the design of the created pagination section.
Having exhaustively described all these steps, we are sure you will have no problem adding numeric pagination to your WordPress website using either method. Since we have also covered some advanced WordPress coding concepts, reading this article will help any intermediate WordPress users expand their existing knowledge. We suggest bookmarking this article, in case you ever need to add the numeric pagination in the future or simply to brush up on the knowledge you have gained reading it.
