What WP-PageNavi does on your site
WP-PageNavi swaps the “Older posts” and “Newer posts” links on your archives for a real pagination bar: page numbers, first and last page, previous and next, and a label such as “Page 3 of 12”. It is built by Lester Chan, has been maintained for about twenty years, and is completely free, with no paid edition.
The plugin does nothing on its own: it provides the wp_pagenavi() template tag, which your theme has to call instead of next_posts_link() and previous_posts_link(). The same function can also paginate a post split into several pages ('type' => 'multipart') or a secondary query passed through the query argument. Wording, number of links and style are set under Settings > WP-PageNavi.
On the front end, it adds one stylesheet, css/wp-pagenavi.css, and the navigation markup, wrapped in an element with the wp-pagenavi class. Version 3.0 dropped the bundled SCB framework, so the plugin now runs on WordPress core APIs alone, but it now requires WordPress 6.8 and PHP 8.2.
Which sites WP-PageNavi suits
- Blogs and magazines with deep archives, where readers want to jump straight to page 10 instead of clicking “Older posts” ten times.
- Classic PHP themes, child or custom, where you can edit
index.php,archive.phporsearch.php. - Developers who want configurable pagination without writing it: class names you can change through filters, a choice of wrapper tag, colors as CSS custom properties.
It is the wrong pick for a block theme, whose templates contain no PHP to call wp_pagenavi() from; the WordPress pagination block does the same job there. It is not an infinite scroll or “Load more” plugin either: every link opens a new page. And if your host still runs PHP 8.1 or older, you will not be offered the current version; our article on end-of-life PHP versions helps you plan the upgrade.
WP-PageNavi strengths and limitations
Strengths
- Very lightweight. One stylesheet, no script in Normal style, and no third-party library since version 3.0.
- Easy to fit into a design. Ten filters rename the classes, the stylesheet inherits the theme’s font, and its two border colors are CSS custom properties.
- Careful accessibility. The current page carries
aria-current, and the first, previous, next and last links reuse WordPress’s own translated labels. - Beyond archives. It paginates secondary queries, multi-page posts and user lists.
- Clean uninstall. Deleting the plugin removes its settings, on every site of a multisite network.
Limitations
- Theme edits required. Nothing appears until the theme calls
wp_pagenavi(), and block themes do not lend themselves to it. - Recent requirements. Since version 3.0 you need WordPress 6.8 and PHP 8.2.
- Stylesheet loaded everywhere. While the option is on, it is added to every public page, even pages without pagination.
- Drop-down style relies on JavaScript. It changes page through an
onchangeattribute written into the HTML, with no fallback button. - Version 3.0 needs attention. A
pagenavi-css.csscopy in the theme must be renamed, and code calling the oldPageNavi_*classes must be updated.
The WP-PageNavi settings we recommend
Every setting lives on one screen, Settings > WP-PageNavi, open only to accounts with the manage_options capability.
| Setting | Recommended value | Why |
|---|---|---|
| Page Navigation Style Settings > WP-PageNavi | Normal | The Drop-down List does not work without JavaScript, and its onchange attribute is blocked by a strict CSP. |
| Use wp-pagenavi.css Settings > WP-PageNavi | Yes if your theme does not style pagination; No if it already does | With No, every public page loads one stylesheet less. |
| Number Of Pages To Show Settings > WP-PageNavi | 5 (the default), fewer if the bar wraps onto two lines on phones | A short bar stays readable on a small screen. |
| Number Of Larger Page Numbers To Show Settings > WP-PageNavi | 3 on a large archive, 0 on a small blog | Jumps such as 10, 20, 30 only help when there are many pages; 0 turns them off. |
| Show Larger Page Numbers In Multiples Of Settings > WP-PageNavi | 10 (the default) | A regular step that readers grasp at once. |
| Always Show Page Navigation Settings > WP-PageNavi | No | Avoids a pointless bar on an archive that fits on a single page. |
| Text For Previous Page and Text For Next Page Settings > WP-PageNavi | The default arrows, or an SVG icon | SVG icons are accepted since version 3.0; leaving a field blank hides that part of the navigation. |
| Updates Plugins > Installed Plugins | Auto-updates on, once the move to version 3.0 has been tested | Future fixes then install without any action on your part. |
- Open page 2 of an archive and check that it shows different posts from page 1; if not, the theme is misusing
query_posts(). - If your theme holds a
pagenavi-css.csscopy, rename itwp-pagenavi.css: since version 3.0 the old name is ignored. - Search your code for
PageNavi_Core::$optionsorscb_*functions and replace them withWP_PageNavi_Options::get()orWP_PageNavi_Options::defaults(). - Tab through the bar with the keyboard, and check on a phone that it does not overflow the screen.
To help visitors find their way beyond pagination, WP-PageNavi pairs well with a breadcrumb trail such as Breadcrumb NavXT. If you are rolling out a CSP, our guide to HTTP security headers explains why event handlers written into the HTML cause trouble.
How secure WP-PageNavi is
At the time of writing, the WPScan and Patchstack vulnerability databases list no published vulnerability for WP-PageNavi. Its attack surface is small: a single settings screen restricted to administrators, no AJAX requests, no public form.
Version 3.0 tightened the code further: link URLs go through esc_url(), navigation text is filtered both on save and on output (script tags and event attributes are stripped, SVG icons included), and unknown setting keys are no longer stored. The capability required for the settings screen can be changed with the wp_pagenavi_capability filter.
The step that matters is still updating (see our guide to plugin auto-updates). WP Masquerade Pro renames the wp-pagenavi folder in file addresses and in the ID of its stylesheet tag, which makes the plugin harder for bots to spot without replacing updates; the wp-pagenavi class stays visible in the code of archives that show the bar.
What WP Masquerade hides for WP-PageNavi
Pro Handled by WP Masquerade Pro only
The free version does not know the traces specific to WP-PageNavi: without Pro, only generator tags are removed, as for any plugin.
Free version
Handled by WP Masquerade Pro only
With Pro
- folder name
- tag IDs
Still visible
- CSS classes
wp-pagenavi (archives using it)
These traces stay because the plugin needs them to work (scripts, styles, cookies) or because they come from the server.
WP-PageNavi FAQ
I activated WP-PageNavi but nothing changed. Why?
The plugin displays nothing by itself: your theme has to call wp_pagenavi() in place of the “Older posts” and “Newer posts” links. Make the change in a child theme so it survives theme updates.
Can I use it with a custom WP_Query?
Yes. Pass your query in the query argument: wp_pagenavi( array( 'query' => $my_query ) ). If page 2 shows the same posts as page 1, the theme is usually misusing query_posts().
Are my settings kept when moving to version 3.0?
Yes. The old pagenavi_options option is copied into wp_pagenavi_options and then deleted automatically; since version 3.0.1 this migration runs on every request, even if nobody opens the dashboard.
How do I change the colors without copying the stylesheet?
Set the --wp-pagenavi-border-color and --wp-pagenavi-border-color-current properties on .wp-pagenavi in your theme’s CSS. For deeper changes, copy css/wp-pagenavi.css into the theme folder as wp-pagenavi.css.
Does deleting WP-PageNavi leave data in the database?
No. Uninstalling removes its two options, plus the old one if it still exists, on every site of a multisite network. Do remove the wp_pagenavi() call from the theme, or wrap it in function_exists(), before deleting the plugin.