How to Display Upcoming Events by Using WP_Query and Advanced Custom Fields

Advanced Custom Fields and WP_Query

In this article I show how to display upcoming events by using WP_Query and Advanced Custom Fields (abbreviation ACF) in a WordPress theme.

I wrote an article How to Use WP_Query to Display Future Events in WordPress Theme where the event date is checked from the scheduled date of the post or the custom post type. That approach lead to situation where the event date is the same as publishing date. If user wants to create an event which will be arranged in the future and it’s published immediately: the event doesn’t show in a list of upcoming events because post_status is changed from the future to the publish. The full list of status parameters can be found from the WP_Query Codex page.

publishing information
Publishing information of post / custom post type.

The problem can be solved by using plugin called Advanced Custom Fields. In this article I don’t tell you how to use ACF but I show the solution, how to create a WP_Query which checks the event date from the ACF attached to the event. I have ACF pro version, but this can be done with the free ACF because you just need one field, not field group.

Prerequisites for to take these instructions in use

  • Development environment up and running
  • WordPress installed
  • Basic WordPress theme structure coded
  • A test page created from admin
  • page-<your-page-name>.php file created
  • Advanced Custom Fields plugin installed
  • Advanced Custom Field configured
    • Field type Date Time picker created (check from the picture below)
    • Correct rules added to ACF (check from the picture below)
  • Event (or your custom post type) or post created from admin
    • Date & Time from ACF set to future
    • Event published (this WP_Query doesn’t show unpublished events)

The Code and the View

The WordPress theme was built for eRacing team and the events are about upcoming practises, races or qualifications. The code is placed in page-test.php file and it creates listing of upcoming events.

This WP_Query differs from the WP_Query used in article How to Use WP_Query to Display Future Events in WordPress Theme so that instead of checking event’s date from the state of the post, it checks it from predefined custom field which is set to be ‘the event date and time’ in this example.

    // 1. Get the content of the page 
    if (have_posts()){
            the_post(); the_content();
    // 2. Save 'date & time now' to variable 
    $date_now = date('Y-m-d H:i:s'); 
    // 3. Define WP_Query
    $futureEvents = new WP_Query(array(
        'post_count'  => 5,
        'post_type'   => 'events',
        'meta_query'  => array(
                   'key'      => 'event_date',
                   'compare'  => '>',
                   'value'    => $date_now,
                   'type'     => 'DATETIME'
         'order'	      => 'ASC',
         'orderby'            => 'meta_value'
     // 4. Get the events according to WP_Query
     if ($futureEvents->have_posts()){
         while($futureEvents->have_posts()) {

             echo "<h5><a href='" . get_permalink() . "'>";
             the_field('event_date'); echo " : &nbsp"; the_title();
             echo "</a></h5>";
The list of upcoming events in ascending order and arranged by checking values from custom field.
  1. Get the content of the page 
    • If you have write a content to the test page via admin console, then you need this loop for fetching the content to the page. 
  2. Save ‘date & time now’ to variable
  3. Define WP_Query 
    • WP_Query is the beef of the code!
    • post_count sets the number of how many posts are fetched.
    • post_type defines the type of the post which you want to show on your page, if you need the normal posts just use post instead of events or if you have your own custom post type use that.
    • meta_query contains custom field parameters ( key=> value pairs)
      • key is the custom field key
      • value is the custom field value
      • type is the custom field type
      • compare is operator to test value
    • order is set to be ascending (from lowest to highest)
    • orderby organises results by custom field value, in this example the field name is called event_date
  4. Get the events according to WP_Query 
    • loop for fetching posts according to predefined WP_Query
    • the_field(‘event_date’) prints the date and time of the event
    • the_title() prints the title of the event
    • the date and the title are wrapped in a tag so that you can click the title and the single event page opens.

The List of References

Understanding WP_Query, meta_query, custom fields and how those work together with the Advanced Custom Fields plugin has demanded a lot of studying from different sources. Luckily ACF has an easy read documentation with the lot of examples, also Codex is very useful for checking what each components really means. Here are my references:

Happy coding!

Do what you love