Date Picker Field

A calendar date selector for choosing a single date value.

Last updated: June 14, 2026

Overview

The Date Picker field renders a text input that opens a calendar popover when clicked, letting the user select a date. It returns the selected date as a formatted string. Use it for maintenance mode end dates, sale countdown dates, event dates, launch dates, or any other date-based setting in your theme.

Field Registration

[
    'id'       => 'event_start_datetime',
    'type'     => 'date_picker',
    'title'    => __( 'Event Start', 'your-textdomain' ),
    'subtitle' => __( 'Date and time the event begins', 'your-textdomain' ),
    'showTime' => true,
    'is12Hour' => true,   // show AM/PM selector
    'default'  => '',
]

Field Options

Option	Type	Required	Description
`id`	`string`	✅	Unique field identifier — used as the option key
`type`	`string`	✅	Must be `date_picker`
`title`	`string`	✅	Label shown above the field
`subtitle`	`string`	—	Smaller descriptive text shown below the label
`desc`	`string`	—	Help text shown below the date input
`default`	`string`	—	Default date string — e.g. `'2026-12-31'`or empty string
`showTime`	`bool`	—	Enable time selection alongside the date. Default: `false`
`is12Hour`	`bool`	—	Use 12-hour clock (AM/PM) when `showTime` is `true`. Default: `false`
`required`	`array`	—	Conditional logic rules — see Conditional Logic

Return Value

Type: string

Returns a date string, or an empty string if nothing has been saved yet.

The format depends on whether showTime is enabled:

Date and time (showTime: true): returns full ISO 8601 format — e.g. '2026-12-31T14:30:00'

Date only (showTime: false — default): returns Y-m-dformat — e.g. '2026-12-31'

// Date only (default)
$date = themeplus_get_option( 'sale_end_date', '' );
// Returns: '2026-12-31'

// With showTime: true
$datetime = themeplus_get_option( 'event_start_datetime', '' );
// Returns: '2026-12-31T14:30:00'

Usage Examples

Showing a sale banner before a deadline

$sale_end = themeplus_get_option( 'sale_end_date', '' );

if ( $sale_end ) {
    $end_timestamp = strtotime( $sale_end );
    $now           = current_time( 'timestamp' );

    if ( $now < $end_timestamp ) {
        echo '<div class="sale-banner">';
        echo '<p>' . sprintf(
            esc_html__( 'Sale ends on %s', 'your-textdomain' ),
            esc_html( date_i18n( get_option( 'date_format' ), $end_timestamp ) )
        ) . '</p>';
        echo '</div>';
    }
}

Maintenance mode with an end date

[
    'id'      => 'enable_maintenance',
    'type'    => 'toggle',
    'title'   => __('Maintenance Mode', 'your-textdomain'),
    'default' => false,
],
[
    'id'       => 'maintenance_end_date',
    'type'     => 'date_picker',
    'title'    => __('Back Online Date', 'your-textdomain'),
    'subtitle' => __('Estimated date when the site will be back online', 'your-textdomain'),
    'required' => ['enable_maintenance', '==', true],
],

$maintenance    = themeplus_get_option( 'enable_maintenance', false );
$end_date       = themeplus_get_option( 'maintenance_end_date', '' );
$end_timestamp  = $end_date ? strtotime( $end_date ) : 0;

if ( $maintenance && ! is_user_logged_in() ) {
    $message = $end_timestamp
        ? sprintf(
            esc_html__( 'We will be back on %s.', 'your-textdomain' ),
            esc_html( date_i18n( get_option( 'date_format' ), $end_timestamp ) )
          )
        : esc_html__( 'We will be back soon.', 'your-textdomain' );

    wp_die( $message, esc_html__( 'Maintenance Mode', 'your-textdomain' ), ['response' => 503] );
}

Countdown timer data attribute

$launch_date = themeplus_get_option( 'launch_date', '' );

if ( $launch_date ) {
    echo '<div class="countdown" data-target="' . esc_attr( $launch_date ) . 'T00:00:00"></div>';
}

Displaying a datetime value

$datetime = themeplus_get_option( 'event_start_datetime', '' );

if ( $datetime ) {
    $timestamp = strtotime( $datetime );

    echo '<p>' . sprintf(
        esc_html__( 'Event starts: %1$s at %2$s', 'your-textdomain' ),
        esc_html( date_i18n( get_option( 'date_format' ), $timestamp ) ),
        esc_html( date_i18n( get_option( 'time_format' ), $timestamp ) )
    ) . '</p>';
}

Comparing two dates

$start = themeplus_get_option( 'event_start_date', '' );
$end   = themeplus_get_option( 'event_end_date',   '' );

if ( $start && $end ) {
    $start_ts = strtotime( $start );
    $end_ts   = strtotime( $end );
    $now      = current_time( 'timestamp' );

    if ( $now >= $start_ts && $now <= $end_ts ) {
        echo '<div class="event-badge">' . esc_html__( 'Happening Now', 'your-textdomain' ) . '</div>';
    }
}

With a conditional field

[
    'id'      => 'enable_coming_soon',
    'type'    => 'toggle',
    'title'   => __('Enable Coming Soon Mode', 'your-textdomain'),
    'default' => false,
],
[
    'id'       => 'coming_soon_launch_date',
    'type'     => 'date_picker',
    'title'    => __('Launch Date', 'your-textdomain'),
    'subtitle' => __('Date when the coming soon page will be automatically disabled', 'your-textdomain'),
    'required' => ['enable_coming_soon', '==', true],
],

Notes

The field returns a date string — always pass it through strtotime() before doing any date comparisons or arithmetic.
When showTime is true, the returned string is a full ISO 8601 datetime ('2026-12-31T14:30:00') — strtotime()handles this correctly. Use date_i18n( get_option( 'time_format' ), $timestamp ) to display the time in the site’s configured format.
is12Hour only affects the UI clock display — the stored value is always in 24-hour ISO format regardless of this setting.
Use date_i18n() instead of date() when displaying dates to site visitors — it respects the WordPress locale and timezone settings.
Use current_time( 'timestamp' ) instead of time() for the current time — it applies the WordPress timezone offset configured in Settings → General.
Always check that the returned value is a non-empty string before calling strtotime() on it, as an empty string will produce unexpected results.

Quick Links