Date Picker

The datepicker field picks a date, a time, or both, from a calendar that Bootstrap 6 styles as its Datepicker, and a time panel. It shows values in the page language, and saves them as 2026-11-02 09:30:00, or as the date (2026-11-02) or time (09:30:00) part alone.

The page language (<html lang>) sets the default date format, the first day of the week and the month and weekday names. An English page keeps the defaults: YYYY-MM-DD dates and weeks that start on Sunday.

Date and time

mode: datetime is the default. One input holds the date and the time, and the calendar has hour and minute controls below the days. Typing in the input works too. An empty field saves as null.

fields:
    published_at:
        label: Published
        type: datepicker
        comment: The calendar carries the time controls, and the value saves as date and time.

Date only

mode: date picks a day, and saves the date part alone.

fields:
    starts_on:
        label: Starts On
        type: datepicker
        mode: date
        comment: A calendar of days, with no time controls.

Time only

mode: time swaps the calendar for a time panel with the hour and minute controls on their own, and saves the time part alone.

fields:
    opens_at:
        label: Opens At
        type: datepicker
        mode: time
        comment: The time panel opens on its own, with sliders for the hour and minute.

Twelve hour clock

twelveHour adds an AM and PM switch to the time controls, in time and datetime modes, and shows the time with AM or PM. The value still saves on a 24 hour clock.

fields:
    closes_at:
        label: Closes At
        type: datepicker
        mode: time
        twelveHour: true
        comment: Picked and shown with AM and PM, and still saved on a 24 hour clock.

Hours only

hoursOnly drops the minute control, for values on the hour. The minutes save as 00.

fields:
    reminder_at:
        label: Reminder Hour
        type: datepicker
        mode: time
        hoursOnly: true
        comment: Only the hour is picked, and the minutes save as 00.

Display format

format takes PHP date characters for the day, weekday, month and year, such as d/m/Y or D, j M Y, and changes only how the date is shown and typed: the value saves as 2026-11-02 either way. Without it the field uses the numeric date of the page language.

fields:
    restock_on:
        label: Restock On
        type: datepicker
        mode: date
        format: D, j M Y
        comment: Shown as Mon, 2 Nov 2026, and saved as 2026-11-02.

Earliest and latest dates

minDate and maxDate disable the days outside the range. They take a date string, such as 2026-01-01, or a Unix timestamp.

fields:
    launch_on:
        label: Launch On
        type: datepicker
        mode: date
        minDate: '2026-01-01'
        maxDate: '2027-06-30'
        comment: Only dates from January 2026 to June 2027 can be picked.

Disabled weekdays

disableDays lists weekday numbers that cannot be picked, from 0 for Sunday to 6 for Saturday.

fields:
    delivery_on:
        label: Delivery On
        type: datepicker
        mode: date
        disableDays: [0, 6]
        comment: Saturdays and Sundays cannot be picked.

Disabled dates

disableDays also takes dates, such as 2026-12-25, mixed with weekday numbers if you like. For a list that changes, name a static method as Class::method. It receives the form's model and returns the weekday numbers and dates, here the end of year holidays.

fields:
    ends_on:
        label: Ends On
        type: datepicker
        mode: date
        disableDays: App\Models\Sample::getHolidayDates
        comment: The end of year holidays come from a static model method.

/**
 * getHolidayDates returns the public holidays the end date picker disables, as a static disableDays method.
 *
 * @return array<int, string>
 */
public static function getHolidayDates(): array
{
    $year = (int) date('Y');

    return [
        "{$year}-12-25",
        "{$year}-12-26",
        ($year + 1).'-01-01',
    ];
}

Year range

yearRange sets the years offered in the calendar's year view, as a number of years either side of the shown year (10 by default) or a [from, to] pair.

fields:
    manufactured_on:
        label: Manufactured On
        type: datepicker
        mode: date
        yearRange: [2015, 2026]
        comment: The year view lists 2015 to 2026.

Week layout

firstDay starts the week on another day, from 0 for Sunday to 6 for Saturday, where the page language decides when it is left out. showWeekNumber adds the week number at the start of each row.

fields:
    review_on:
        label: Review On
        type: datepicker
        mode: date
        firstDay: 1
        showWeekNumber: true
        comment: Weeks start on Monday, with the week number at the start of each row.

Midnight by default

In datetime mode, picking a day on an empty field fills in the current time. defaultTimeMidnight fills in 00:00 instead.

fields:
    expires_at:
        label: Expires
        type: datepicker
        defaultTimeMidnight: true
        comment: Picking a date fills the time with 00:00 rather than the current time.

Timezone

Dates are stored in the application timezone. Once a timezone resolver is set with Ui::resolveTimezoneUsing() (see URLs and Timezones), datetime values show in the viewer's timezone and save back in the application timezone.

useTimezone: false shows and saves the value as stored, for times that belong to a place rather than a viewer, such as an event in its own city. Date and time modes never convert.

fields:
    webinar_at:
        label: Webinar
        type: datepicker
        useTimezone: false
        comment: Shown and saved exactly as stored, whatever the viewer's timezone.

Read-only

A readOnly field shows the value in an input whose pickers do not open, and posts the value unchanged.

fields:
    inspected_at:
        label: Inspected
        type: datepicker
        readOnly: true
        comment: Shown, and saved as it is, but the pickers do not open.

Disabled

A disabled field also keeps the pickers closed, and its value is not saved.

fields:
    discontinued_on:
        label: Discontinued On
        type: datepicker
        mode: date
        disabled: true
        comment: Shown, but the pickers do not open and the value is not saved.

Preview

In preview mode the server formats the value with format when set, or else the long locale format of the mode: October 20, 2026 for a date, 2:30 PM for a time, and the weekday, date and time for datetime. This example's form is made with previewMode on.

fields:
    sold_at:
        label: Sold
        type: datepicker

The control on its own

The datepicker control works without the form widget, in any markup. Wrap the inputs in an element with data-control="datepicker" and the options as data-* attributes, put a visible text input marked data-datepicker (or data-timepicker for a time) inside it, and add a hidden input marked data-datetime-value that holds the value and carries the name that posts.

<div
    class="field-datepicker"
    data-control="datepicker"
    data-mode="date"
    data-min-date="2026-01-01"
    data-show-week-number="true">
    <label class="form-control form-adorn form-adorn-end">
        <span class="form-adorn-icon" aria-hidden="true">
            <i class="ph ph-calendar-blank"></i>
        </span>
        <input type="text" class="form-ghost" autocomplete="off" aria-label="Meeting date" data-datepicker />
    </label>
    <input type="hidden" name="meeting_on" value="2026-11-12" data-datetime-value />
</div>

The wrapper takes these attributes:

Attribute	Description
data-mode	date, datetime or time. Default: from the inputs found.
data-format	the display format in YYYY, YY, MMMM, MMM, MM, M, dddd, ddd, DD, Do and D tokens, with [text] for literal text.
data-min-date, data-max-date	the earliest and latest dates that can be picked, as YYYY-MM-DD.
data-year-range	years either side in the year view, or a JSON [from, to] pair.
data-disable-days	a JSON list of weekday numbers and YYYY-MM-DD dates that cannot be picked.
data-first-day	the first day of the week, 0 for Sunday.
data-show-week-number	true shows the week numbers.
data-twelve-hour, data-hours-only	1 turns on the matching option.
data-default-time-midnight	present to fill in 00:00 rather than the current time.
data-timezone	the timezone of the shown value, used when filling in the current date and time.

Options

Option	Description
mode	datetime, date or time. Default: datetime.
format	the date display format, in PHP date characters. Default: the numeric date of the page language.
minDate	the earliest date that can be picked, as a date string or timestamp.
maxDate	the latest date that can be picked, as a date string or timestamp.
disableDays	weekday numbers (0 is Sunday) and Y-m-d dates that cannot be picked, or a Class::method that returns them.
yearRange	years either side of the shown year in the year view, or a [from, to] pair. Default: 10.
firstDay	the first day of the week, 0 for Sunday to 6 for Saturday. Default: from the page language.
showWeekNumber	shows the week numbers. Default: false.
twelveHour	picks and shows times with AM and PM. Default: false.
hoursOnly	picks the hour only, and saves the minutes as 00. Default: false.
defaultTimeMidnight	fills in 00:00 rather than the current time when a day is picked. Default: false.
useTimezone	converts datetime values between the viewer's and the application timezone. Default: true.

The field also takes the common field properties, such as readOnly and disabled.