Date Range

A paired date picker that captures both a start date and an end date in a single field. Each date uses its own Flatpickr calendar. Returns an associative array with start and end keys formatted according to your return format.

Settings

Setting	Default	Description
Display Format	`Y-m-d`	PHP date format used in the admin calendar UI.
Return Format	`Y-m-d`	PHP date format applied to the stored value returned by `get_field()`.
First Day of Week	`Monday` (1)	Which day the calendar week starts on. 0 = Sunday, 1 = Monday … 6 = Saturday.

Return values

Returns an associative array with start and end keys. Both values are formatted strings according to your Return Format setting.

$range = get_field('event_dates');
// [
//   'start' => '2026-06-01',
//   'end'   => '2026-06-14',
// ]

If neither date is set, get_field() returns false.

Usage

Displaying a formatted date range

$range = get_field('event_dates');

if ($range && $range['start'] && $range['end']) {
    $start = new DateTime($range['start']);
    $end   = new DateTime($range['end']);

    echo '<p class="event-dates">';
    echo esc_html($start->format('F j')) . ' – ' . esc_html($end->format('F j, Y'));
    echo '</p>';
    // "June 1 – June 14, 2026"
}

Checking if today falls within the range

$range = get_field('sale_period');

if ($range) {
    $today = new DateTime('today');
    $start = new DateTime($range['start']);
    $end   = new DateTime($range['end']);

    if ($today >= $start && $today <= $end) {
        echo '<div class="sale-banner">Sale is active!</div>';
    }
}

WP_Query: filter events by date range overlap

// Find events that haven't ended yet
$posts = get_posts([
    'post_type'  => 'event',
    'meta_query' => [[
        'key'     => 'event_dates_end', // ACF sub-key for end date
        'value'   => date('Y-m-d'),
        'compare' => '>=',
        'type'    => 'DATE',
    ]],
]);

Calculating the duration

$range = get_field('booking_dates');

if ($range && $range['start'] && $range['end']) {
    $start    = new DateTime($range['start']);
    $end      = new DateTime($range['end']);
    $interval = $start->diff($end);
    $nights   = $interval->days;

    echo 'Duration: ' . esc_html($nights) . ' night' . ($nights !== 1 ? 's' : '');
}