Date Time Picker

Documentation Field Types Date Time Picker

Last updated Feb 17, 2022

Description

The Date Time Picker field creates a jQuery date & time selection popup.

Screenshots

Changelog

• Added in version 5.3.9.

Settings

• Display Format
  The date format that is displayed when selecting a date.

• Return Format
  The date format that is returned when loading the value. Please note that the value is always saved as Y-m-d H:i:s (YYYY-MM-DD HH:II:SS) in the database.

• Week Starts On
  Specifies the day to start the week on.

Template usage

The Date Time Picker field returns a date-time string using the Return Format setting.

Display value

This example demonstrates how to display a date-time value.

<p>Event starts: <?php the_field('start_date'); ?></p>

Query posts sorted in order

This example demonstrates how you can query posts sorted in order of a custom field value.

<?php

$posts = get_posts( array(
    'posts_per_page' => -1,
    'post_type'      => 'event',
    'order'          => 'ASC',
    'orderby'        => 'meta_value',
    'meta_key'       => 'start_date',
    'meta_type'      => 'DATETIME',
));

if( $posts ) {
    foreach( $posts as $post ) {
        // Do something.
    }
}

Query posts within date range

This example demonstrates how you can query posts to find events that are currently happening today.

<?php 

// Find todays date in Ymd format.
$date_now = date('Y-m-d H:i:s');

// Query posts using a meta_query to compare two custom fields; start_date and end_date.
$posts = get_posts( array(
    'post_type' => 'event',
    'meta_query' => array(
        array(
            'key'           => 'start_date',
            'compare'       => '<=',
            'value'         => $date_now,
            'type'          => 'DATETIME',
        ),
        array(
            'key'           => 'end_date',
            'compare'       => '>=',
            'value'         => $date_now,
            'type'          => 'DATETIME',
        )
    ),
));

if( $posts ) {
    foreach( $posts as $post ) {
        // Do something.
    }
}

Query upcoming posts

This example demonstrates how to query and loop over upcoming events (in the next 7 days) ordered by a custom date time field value.

<?php

// Find current date time.
$date_now = date('Y-m-d H:i:s');
$time_now = strtotime($date_now);

// Find date time in 7 days.
$time_next_week = strtotime('+7 day', $time_now);
$date_next_week = date('Y-m-d H:i:s', $time_next_week);

// Query events.
$posts = get_posts(array(
    'posts_per_page' => -1,
    'post_type'      => 'event',
    'meta_query'     => array(
        array(
            'key'         => 'start_date',
            'compare'     => 'BETWEEN',
            'value'       => array( $date_now, $date_next_week ),
            'type'        => 'DATETIME'
        )
    ),
    'order'          => 'ASC',
    'orderby'        => 'meta_value',
    'meta_key'       => 'start_date',
    'meta_type'      => 'DATETIME'
));

if( $posts ) {
    foreach( $posts as $post ) {
        // Do something.
    }
}

Save as unix timestamp

This example demonstrates how to change the value saved from the standard ‘Y-m-d H:i:s’ string to a unix timestamp number. This may be necessary to maintain compatibility with third party date time picker fields.

<?php 

add_filter('acf/update_value/type=date_time_picker', 'my_update_value_date_time_picker', 10, 3);

function my_update_value_date_time_picker( $value, $post_id, $field ) {
    return strtotime( $value );
}

Notes

Database format

The value selected can be returned and displayed in different formats but will be saved to the database as ‘Y-m-d H:i:s’. This format is used throughout the WordPress database tables and will allow for straight-foward database querying.

Date format strings

To customize the Display Format and Return Format settings further, refer to the full list of date format strings within the DateTime::createFromFormat() documentation.

Date formats in JavaScript

Some JavaScript libraries might format PHP date strings differently. For example, the following date function in PHP:

echo date('F j, Y @ g:i a');

Will output something like:

November 19, 2021 @ 1:49 pm

However, if you pass this value to the somethign like the jQuery UI DatePicker Widget, it will see the @ as a special character to be formatted return the Unix timestamp, which is not ideal.

In order to fix this, you can use the acf/settings/php_to_js_date_formats filter, which will convert any instance of the @ symbol to '@', and thereby treated as a string in JavaScript, instead of a character to be replaced.

add_filter('acf/settings/php_to_js_date_formats', 'support_at_symbol_in_date_format', 10, 1);
function support_at_symbol_in_date_format($formats) {
    $formats['@'] = "'@'";
    return $formats;
}

Translations

If you require the date to be displayed in a non English language, WordPress contains a function called date_i18n() which will perform the translation for you.

<?php

// Load field value and convert to numeric timestamp.
$unixtimestamp = strtotime( get_field('date') );

// Display date in the format "l d F, Y".
echo date_i18n( "l d F, Y", $unixtimestamp );

Related

• Field Types: Date Picker
• Guides: How to Query Posts by Custom Fields
• Guides: Order posts by custom fields