Date Pagination

Paginate your posts by year, month or day.

This WordPress plugin is aimed at developers and provides an easy way to paginate posts by year, month or day in theme templates. It uses the native WordPress pagination functions for display of the pagination links.

Use the new date_pagination_type query argument with a custom query (WP_Query) or with the ‘pre_get_posts‘ action, and this plugin will do the rest. Use three new functions in your (child) theme template files to get the current, next and previous date. See Functions

Plugin support for this plugin from the plugin author will be minimal as this is a plugin made for developers. If you encounter problems see the troubleshooting steps first.

Bug reports, feature requests and other issues can be reported through the GitHub issues system.


**Note** This plugin intentionally doesn’t work in date based archives. See this plugin to paginate by date in date based archives.

Date pagination with pre_get_posts

Set the date pagination by using the date_pagination_type query argument. Conditional tags let you choose where you want to use date pagination.


Set the pagination to monthly on the home page. Use this example in your (child) theme’s functions.php file.

add_action( 'pre_get_posts', 'monthly_paginated_home_query' );
function monthly_paginated_home_query( $query ) {

	// not a wp-admin page and the query is for the main query
	if ( !is_admin() && $query->is_main_query() ) {

		//  on the home page only
		if ( is_home() ) {

			// set the date pagination to 'monthly'
			$query->set('date_pagination_type', 'monthly'); 

			// set other arguments here

Date pagination with WP_Query

See the WP_Query loop example.


There are three new functions you can use in your (child) theme’s template files.

<php km_dp_get_current_date_label( $format, $query ); ?>

<php km_dp_get_next_date_label( $format, $query ); ?>

<php km_dp_get_previous_date_label( $format, $query ); ?>

Use the functions to get the current, next and previous date. They all share the same arguments $format and $query. The $query argument is only needed if you use a custom query (WP_Query).


(string)(optional) PHP date format
(object)(optional) WP_Query object that is paginated by year, month or day.


Normal loop with date pagination set by pre_get_posts

Example of using the new functions in a (child) theme template file with monthly pagination set by the pre_get_posts action in your (child) theme’s functions.php file. See the pre_get_post code example above.

<?php if ( have_posts() ) : ?>
		// Echo current date with format 'F Y' ( e.g. November 2010 ).
		echo 'Current Date: ';
		echo km_dp_get_current_date_label( 'F Y' );

	<!-- The Loop -->
	<?php while ( have_posts() ) : the_post(); ?>
		<!-- Your loop code here -->
	<?php endwhile; ?>

	// default labels
	$next_label = 'Previous Month';
	$prev_label = 'Next Month';

	// Check if functions exists (plugin is activated)
	if ( function_exists( 'km_dp_get_next_date_label' ) ) {
		$next_label = km_dp_get_next_date_label( 'F Y' );

	if ( function_exists( 'km_dp_get_previous_date_label' ) ) {
		$prev_label = km_dp_get_previous_date_label( 'F Y' );

	<!-- WordPress core pagination functions (see the Codex) -->
	<?php next_posts_link( $next_label ); ?>
	<?php previous_posts_link( $prev_label ); ?>
<?php else:  ?>
	<p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

WP_Query loop with date pagination

Example of using the new functions in a (child) theme template file. The monthly pagination is set with the new date_pagination_type query argument.

// Set the paged variable (see: ).
$paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1;

// Example arguments.
$args = array(

	// set the date pagination to 'monthly'
	'date_pagination_type' => 'monthly', // 'yearly', 'monthly', 'daily'
	'paged'                => $paged,

	// Add your own query arguments here
	'post_type'            => array( 'post' ),
	'ignore_sticky_posts'  => true,

// The custom query.
$the_query = new WP_Query( $args );

// Variable $the_query is the query object.
// Don't forget to add the query object to the new functions when using a custom query;

<?php if ( $the_query->have_posts() ) : ?>

		// Echo current date with format 'F Y' ( e.g. November 2010 ).

		echo 'Current Date: ';
		echo km_dp_get_current_date_label('F Y', $the_query);

	<!-- The custom query Loop -->
	<?php while ( $the_query->have_posts() ) : $the_query->the_post(); ?>

		<!-- Your loop code here -->
	<?php endwhile; ?>

	// Date Pagination.

	// Default labels.
	$next_label = 'Previous Page';
	$prev_label = 'Next Page';	

	// Check if functions exists (plugin is activated).
	if ( function_exists( 'km_dp_get_next_date_label' ) ) {
		$next_label = km_dp_get_next_date_label( 'F Y', $the_query );

	if ( function_exists( 'km_dp_get_previous_date_label' ) ) {
		$prev_label = km_dp_get_previous_date_label( 'F Y', $the_query );

	<!-- WordPress core pagination functions (see the Codex) -->
	// Set max_num_pages for next_posts_link() when using a custom query (see the Codex).
	// Get the max_num_pages from the custom query object ($the_query)
	next_posts_link( 'Previous month: ' . $next_label, $the_query->max_num_pages );
	<?php previous_posts_link( 'Next month: ' . $prev_label ); ?>

	<?php wp_reset_postdata(); ?>
<?php else:  ?>
	<p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

Troubleshooting Steps

The same troubleshooting steps for WordPress pagination functions apply to this plugin.

Troubleshooting steps if you queried the loop with new WP_Query or query_posts.
Did you set the paged parameter?
Is pagination broken on a static front page?
Did you reset the loops if there are multiple loops?
Did you add the $max_pages to the next_posts_link() function?
Did you add the total to the paginate_links() function?

42 thoughts on “Date Pagination

  1. Hi,

    I have been looking for this type of plugin for a long time ….. think the idea of using dates for pagination is the way to go, especially for sites that generate a lot of content.

    I am more a designer, with an appreciation of development … but this is a little bit past my skill set at the moment.
    Are there any plans to release an out of the box plugin? Would really love to get this running on the sites I work with.

    Many thanks in advance

    1. Hi David,

      Unfortunately this is as out of the box as it gets. It’s up to a theme where to display pagination, and what functions (or pagination plugins) are used. The plugin can’t know, filter or detect this. For the most part the plugin will be compatible with themes that use the native WordPress pagination functions.

      Where do you encounter problems? On what pages do you want date pagination?

  2. Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates.

    I’ve been looking for a plug-in like this for quite some time and
    was hoping maybe you would have some experience with something like this.
    Please let me know if you run into anything.
    I truly enjoy reading your blog and I look forward to your new updates.

  3. Is there any way this plugin can be altered so that the posts within each day can be sorted by a meta value? If I add a normal WP ‘orderby’=>’meta_value_num’ into this current, it spits out the days in order of votes :/

      1. It seems that WordPress allows you to put two variables in the orderby parameter, first one being dominant, but if I just put ‘date’, then it orders by the timestamp, not by the day. So I will have to create another meta field that just stores the day of publishing instead of the timestamp. If you have a better solution, please let me know!

  4. Hi keesiemeijer,
    Good job with your plugin!
    I am working on the blog section of this website
    to get the posts in monthly pagination.
    I am using this plugin to have the possibility to publish post/events coming in next months.
    Problem is that the first posts on the blog will be future dates.

    Is there a way to use your plugin in order to display posts from the current month, when you land on the blog page?
    I’d really appreciate your help,
    if something sounds confusing I will post the code in codepen or pastebin


  5. hello keesiemeijer,

    I’m trying to use this pagination with the option set as daily.

    using the code below though just gives me the current date for each link. They display the correct posts though, they just doesn’t display the correct date.


    if ( function_exists( 'km_dp_get_next_date_label' ) ) {
        $next_label = km_dp_get_next_date_label( 'F j, Y' );
    if ( function_exists( 'km_dp_get_previous_date_label' ) ) {
        $prev_label = km_dp_get_previous_date_label( 'F j, Y' );
      1. Yes, it displays in pagination link. $now is only for compare dates. By the way, is it difficult to put an option ‘weekly’ to your plugin?

  6. Great plugin! This is exactly what I’m looking for, however I’m wondering if there was a way I could get each page to show 2 month of posts instead of just one month. A sort of bi-monthly pagination.
    Let me know if you think this is possible and how I could implement it.

    1. Hi akramsideas

      That can be done with some changes to the plugin. What kind of labels do you want for the next and previous links? With dates in them or just plain “Next posts” “Previous posts”

  7. I’m ran into an issue with the plugin the minute I posted my first 2015 post. It caused the previous month to suddenly add images and revisions as posts in the loop. It was really weird.

    I’ve disabled the plugin at the moment, but was wondering if you might have an idea what could be causing the issue.


      1. Hey
        This doesn’t work for me . basically i want the two month pagination showing posts of this month and next month on one page and future posts like Nov is going on January and Feb posts on next page. and say if December having no posts then it should show Nov and Jan posts on one page and Feb and march posts on next page pagination.

        Pls reply ASAP.

  8. I’ve got kind of an odd situation for you. My client is using this plugin to create archives by year, but they want the first year in the archive to be 2014, the next 2013, etc. I can do this by setting “order” to “DESC,” but then the posts themselves show up in descending order as well. Is there any way to have the pages go in descending order, but the posts in ascending? I.E. January would be first, February second, March third, but he pages would go 2014, 2013, 2012?

    1. My theory is to create an array, reverse the array, and output, but I’m having some trouble with that getting the old dates rather than the new. Will report back as I progress…

      1. Ah, just figured it out completely. Stored each post as a value in an array, reversed the arrays, then output the values using a foreach loop. Works perfectly πŸ™‚

  9. Hi,
    WordPress database error: [Column ‘ID’ in field list is ambiguous]
    SELECT YEAR(post_date) AS `year`, count(ID) as posts FROM ahf_posts JOIN ahf_icl_translations t ON ahf_posts.ID = t.element_id AND t.element_type = ‘post_event’ JOIN ahf_icl_languages l ON t.language_code=l.code AND WHERE 1=1 AND ahf_posts.post_type = ‘event’ AND (ahf_posts.post_status = ‘publish’ OR ahf_posts.post_status = ‘private’) AND t.language_code=’ur’ GROUP BY YEAR(post_date) ORDER BY ahf_posts.post_date DESC

    i am receiving this error.. i am using wpml plugin…

  10. Hi, I’m trying using your plugin. It works ok on the main language, but it does not show anything for the secondary language. I’m using wpml and your plugin by shortcode in the single post page (single.php) via do_shortcode function. What can I do? Thanks

  11. I love the Custom Post Type Date Archive, but is there a way for it to get along with this plugin, or for the CPT Date Archives to have daily pagination? Maybe Date Archives Pagination is for this purpose? It doesn’t seem to have much documentation so I didn’t know if it is a working plugin. I know this post is a little old, but the plugins are so perfect for what I’m working on. Thanks for any help you can offer!

  12. Hi Kessie,

    I found your plugin and it saves me lots of work.
    I’m doing monthly pagination and I wonder if there’s any way to show the page for the current month, instead of future month, for my event post (custom post type)?

    Thanks & Regards,

  13. Hi Kessie, I have copy and pasted your “WP_Query loop with date pagination” example into a page template, but setting ‘date_pagination_type’ => ‘daily’ displays monthly instead of daily archives. Have I forgot something to make the ‘daily’ archives work? Thanks!

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s