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.
$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.
// 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.
// 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.
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.
// 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 );
We use cookies to offer you a better browsing experience, analyze site traffic and personalize content. Read about how we use cookies and how you can control them in our
Privacy Policy
. If you continue to use this site, you consent to our use of cookies.
Got it
