Date Picker

Basic Usage

The DatePicker field renders a calendar-based date picker. By default, it operates in single-date mode.

Example

Birthday

Mar 12, 2026

DatePicker::make('birthday');

Modes

The date picker supports five selection modes. It renders in single-date mode by default. Calling a mode method also adds the matching validation rule.

Birthday

Mar 12, 2026

Vacation

Aug 3, 2026 - Aug 9, 2026

Holidays

3 dates selected

Billing month

July 2026

Graduation year

2028

Single Date

Pick a single date. Call single() when you want to explicitly add a date validation rule.

DatePicker::make('birthday')->single();

Date Range

Pick a start and end date. Adds an array validation rule.

DatePicker::make('vacation')->range();

Multiple Dates

Pick multiple individual dates. Adds an array validation rule.

DatePicker::make('holidays')->multiple();

Month Picker

Pick a month and year. Validates against date_format:Y-m.

DatePicker::make('billing_month')->month();

Month picker values are submitted as YYYY-MM, such as 2026-07.

Year Picker

Pick a year. Validates as an integer between 1900 and 2100.

DatePicker::make('graduation_year')->year();

Year picker values are submitted as YYYY, such as 2026.

Date and Time

Enable time selection alongside the date. This changes the value format to include hours and minutes.

Example

Starts at

Sep 14, 2026 2:30 PM

Starts at (24-hour)

Sep 14, 2026 6:45 PM

DatePicker::make('starts_at')->withTime();
DatePicker::make('starts_at_24')->withTime()->use24HourTime();

Time controls are available in single() and range() modes. They are not rendered for multiple(), month(), or year() values.

24-Hour Format

Use 24-hour time instead of 12-hour with AM/PM:

DatePicker::make('starts_at')->withTime()->use24HourTime();

Timezone

Use timezone() for UTC database timestamps that should display in the user's local timezone. Without it, date-time values are submitted and stored exactly as entered.

DatePicker::make('webinar_starts_at')
    ->withTime()
    ->use24HourTime()
    ->timezone('Europe/Amsterdam');

For example, a database value of 2026-07-15 12:00:00 UTC renders as Jul 15, 2026 14:00 in Amsterdam. Submitting 2026-07-15 14:00 converts the value back to 2026-07-15 12:00 UTC for storage.

Call validated() before storing form data. It returns the timezone-adjusted UTC value after field transformations have run. The lower-level validate() method returns Laravel's raw validated payload.

This only applies when withTime() is enabled in single() or range() mode. Single values are converted as strings and range values are converted item by item. Multiple, month, and year values are not timezone converted. The conversion uses the configured valueFormat().

Min and Max Date

Constrain the selectable date range. Both methods automatically add after_or_equal and before_or_equal validation rules for scalar date submissions. For range() or multiple() values, every submitted date is validated against the same bounds.

Example

Appointment

May 20, 2025

DatePicker::make('appointment')
    ->minDate('2025-01-01')
    ->maxDate('2025-12-31');

Use today's date dynamically:

DatePicker::make('start_date')
    ->minDate(now()->format('Y-m-d'));

Initial Open Date

Use openTo() to open an empty picker on a specific month or year instead of today. Existing field values are shown first.

DatePicker::make('release_date')
    ->openTo('2027-03-01');

Disabled Dates

Disable specific dates in the calendar UI and reject those dates during backend validation:

DatePicker::make('appointment')->disabledDates([
    '2025-12-25',
    '2025-12-26',
    '2026-01-01',
]);

For range() or multiple() values, each submitted date is checked.

Presets

Add quick-select buttons for common date values. Presets are supported in every mode, but the value must use the same shape that mode submits.

Mode	Preset value shape
single()	Date string, such as '2026-07-19'.
single()->withTime()	Date-time string, such as '2026-07-19 09:00'.
range()	Exactly two strings: [start, end].
range()->withTime()	Exactly two date-time strings: [start, end].
multiple()	An array of date strings. Multiple-date arrays are supported only for multiple mode.
month()	Month string, such as '2026-07'.
year()	Year string, such as '2026'.

The frontend applies preset values as-is, so format each value to match the mode's submitted value.

Example

Period

Jul 13, 2026 - Jul 17, 2026

DatePicker::make('period')
    ->range()
    ->presets([
        ['label' => 'Launch week', 'value' => ['2026-07-13', '2026-07-17']],
        ['label' => 'Conference', 'value' => ['2026-08-10', '2026-08-14']],
        ['label' => 'Review sprint', 'value' => ['2026-09-07', '2026-09-18']],
    ]);

Multiple mode accepts arrays with more than two dates:

DatePicker::make('holidays')->multiple()->presets([
    ['label' => 'Office closure', 'value' => ['2026-12-24', '2026-12-25', '2026-12-31']],
]);

Display and Value Format

Customize how the date is displayed to the user and how it is submitted.

Example

Birthday

12/03/2026

DatePicker::make('birthday')
    ->displayFormat('DD/MM/YYYY')    // What the user sees
    ->valueFormat('YYYY-MM-DD');     // What gets submitted

Token	Description	Example
YYYY	4-digit year	2025
YY	2-digit year	25
MMMM	Full month	January
MM	2-digit month	01-12
M	Month without padding	1-12
DD	2-digit day	01-31
HH	24-hour hour	00-23
mm	Minutes	00-59
ss	Seconds	00-59
MMM	Abbreviated month	Jan, Feb
D	Day without padding	1-31

Default display format: MMM D, YYYY. Default value format: YYYY-MM-DD (or YYYY-MM-DD HH:mm when withTime is enabled).

displayFormat() controls the visible date text for day-based modes: single(), range(), and multiple(). valueFormat() controls submitted date strings for those modes, including the date-time string when withTime() is enabled. Neither method changes the fixed submission shape of month() (YYYY-MM) or year() (YYYY).

Existing values, presets, standalone values, and submitted values must all match the configured value format. Date constraints, openTo(), markers, and highlighted dates remain ISO-style date strings such as 2026-04-16.

Placeholder

Set the text shown before a value is selected:

DatePicker::make('birthday')->placeholder('Choose a birthday');

The default placeholder is Select date in every mode.

Clearable

Allow the user to clear the selected date:

DatePicker::make('deadline')->clearable();

Number of Months

Show multiple months side by side. Useful for range selection:

DatePicker::make('vacation')->range()->numberOfMonths(2);

First Day of Week

Set which day the week starts on. 0 is Sunday, 1 is Monday, and so on.

DatePicker::make('date')->firstDayOfWeek(1);  // Monday

Inline

Use inline() when the date grid should stay visible on the page instead of opening from a dropdown. This is the inline date-picking API for booking, scheduling, and availability interfaces:

Example

Date

DatePicker::make('date')->inline();

Week Numbers

Display ISO week numbers in the calendar:

Example

Date

DatePicker::make('date')->showWeekNumbers();

Markers

Add colored dots on specific dates in the calendar to indicate events or deadlines:

DatePicker::make('date')->markers([
    ['date' => '2025-06-15', 'color' => 'blue', 'tooltip' => 'Team meeting'],
    ['date' => '2025-06-20', 'color' => 'red', 'tooltip' => 'Deadline'],
    ['date' => '2025-07-01', 'color' => 'green'],
]);

Key	Required	Description
date	Yes	The date string (e.g., 2025-06-15)
color	No	Dot color (e.g., blue, red, green)
tooltip	No	Tooltip text on hover

Highlighted Dates

Highlight specific dates with a background color:

DatePicker::make('date')->highlightedDates([
    '2025-06-15',
    '2025-06-20',
    '2025-07-01',
]);

Combining Options

DatePicker::make('event_date')
    ->range()
    ->withTime()
    ->use24HourTime()
    ->timezone('Europe/London')
    ->minDate('2025-01-01')
    ->maxDate('2026-12-31')
    ->openTo('2026-06-01')
    ->numberOfMonths(2)
    ->firstDayOfWeek(1)
    ->showWeekNumbers()
    ->clearable()
    ->placeholder('Select a date range')
    ->required()
    ->precognitive();

Shared Field APIs

The date picker methods above compose with shared field APIs. You may use Form Class for labels, help text, and placeholders, Model Binding for default(), Validation for rules, required fields, and precognition, Styling for classes and presentation helpers, Conditional Visibility, and Authorization.

Using the Component Directly

DatePicker is exported from each package's components subpath. You may use it for standalone date selection or while rendering forms manually.

Vue

<script setup lang="ts">
import { DatePicker } from '@inertiaui/form-vue/components'
import { ref } from 'vue'

const vacation = ref<string | string[] | [string, string] | null>(null)
const presets = [
    { label: 'Next week', value: ['2026-07-27 09:00', '2026-07-31 17:00'] },
    { label: 'Conference', value: ['2026-08-10 09:00', '2026-08-14 17:00'] },
]
const disabledDates = ['2026-08-03', '2026-08-04']
const markers = [{ date: '2026-08-10', color: 'blue', tooltip: 'Conference begins' }]
const highlightedDates = ['2026-08-14']
const trackFocus = () => {}
</script>

<template>
    <DatePicker
        v-model="vacation"
        id="vacation"
        name="vacation"
        label="Vacation"
        help="Choose the travel window."
        placeholder="Select travel dates"
        mode="range"
        with-time
        :use-24-hour-time="true"
        min-date="2026-07-01"
        max-date="2026-08-31"
        :disabled-dates="disabledDates"
        :presets="presets"
        display-format="MMM D, YYYY"
        value-format="YYYY-MM-DD HH:mm"
        clearable
        :number-of-months="2"
        :week-starts-on="1"
        show-week-numbers
        open-to="2026-08-01"
        :markers="markers"
        :highlighted-dates="highlightedDates"
        data-testid="vacation-picker"
        @focus="trackFocus"
    />
</template>

React

import { useState } from 'react'
import { DatePicker } from '@inertiaui/form-react/components'
import type { DatePickerProps } from '@inertiaui/form-react/components'

const presets = [
    { label: 'Next week', value: ['2026-07-27 09:00', '2026-07-31 17:00'] },
    { label: 'Conference', value: ['2026-08-10 09:00', '2026-08-14 17:00'] },
]
const disabledDates = ['2026-08-03', '2026-08-04']
const markers = [{ date: '2026-08-10', color: 'blue', tooltip: 'Conference begins' }]
const highlightedDates = ['2026-08-14']

export default function VacationPicker() {
    const [vacation, setVacation] = useState<DatePickerProps['value']>(null)
    const trackFocus = () => {}

    return (
        <DatePicker
            value={vacation}
            onValueChange={setVacation}
            id="vacation"
            name="vacation"
            label="Vacation"
            help="Choose the travel window."
            placeholder="Select travel dates"
            mode="range"
            withTime
            use24HourTime
            minDate="2026-07-01"
            maxDate="2026-08-31"
            disabledDates={disabledDates}
            presets={presets}
            displayFormat="MMM D, YYYY"
            valueFormat="YYYY-MM-DD HH:mm"
            clearable
            numberOfMonths={2}
            weekStartsOn={1}
            showWeekNumbers
            openTo="2026-08-01"
            markers={markers}
            highlightedDates={highlightedDates}
            data-testid="vacation-picker"
            onFocus={trackFocus}
        />
    )
}

Native attributes and listeners target the underlying trigger element. See Native Attributes And Events.