DatePicker
Choose a date, time or date and time. Calendar modes use local Date values; picker="time" uses time strings. Use DateRangePicker for ranges.
Basic usage
Set an initial date with defaultValue; choosing a date closes the panel. Use null for an empty value.
Examples
Controlled value and clearing
Manage selection with value and onChange. Calendar modes provide both a Date and a formatted string; clearing returns null and ''. Reset application state when resetting a controlled form field.
Interaction states
disabled disables the whole control. readOnly keeps a read-only value that cannot be changed. inputReadOnly prevents typing but still allows panel selection.
Picker granularity
Use picker to select a year, quarter, month or week. The returned Date is the start of that period. ConfigProvider sets the first weekday with weekStartsOn, defaulting to Monday.
Restrict selectable dates
minDate / maxDate include their boundaries, and returning true from disabledDate disables a date. This example allows weekdays in October only. Restrictions apply to typing and panel selection without clearing an existing value; revalidate it in the application when business rules change. Datetime mode compares complete timestamps against its bounds.
Date and time
With picker="datetime", choose a date and time, then select OK to commit. This mode defaults to needConfirm={true}; an outside click discards an unconfirmed date and time.
Time only
picker="time" uses 24-hour HH:mm strings for its value and onChange, returning null when cleared. With showSeconds, it uses HH:mm:ss. Set minTime / maxTime for time bounds, or disabledTime for business restrictions.
12-hour time and seconds
use12Hours changes display only; values remain in 24-hour format. minuteStep / secondStep set adjustment steps while retaining existing off-step values. When seconds are hidden, committed seconds are 0.
Display format and form submission
format changes display and the string argument of onChange, not the canonical FormData value. This example displays DD/MM/YYYY and submits YYYY-MM-DD. Clearing submits an empty string; resetting an uncontrolled field restores defaultValue.
Canonical values are date: YYYY-MM-DD, year: YYYY, quarter: YYYY-QN, month: YYYY-MM and week: YYYY-Www; datetime uses YYYY-MM-DD HH:mm[:ss]. Dates use local time. Handle business timezone conversion in the application rather than treating UTC date strings as local calendar values.
String formats support YYYY, MM, DD, HH, mm, ss and Q. Escape literals with brackets, for example YYYY-[Q]Q. If a function formatter produces text the default parser cannot recognize, provide parse, returning null on failure. See Form for other form configuration.
Date shortcuts
Use presets for common dates. Values may be a Date or a function that synchronously returns a Date, not a Promise. Choosing a valid preset commits immediately and closes the panel without waiting for OK. Configure Today with showToday / todayText; use renderExtraFooter for custom footer content and handle its business actions in the application.
Input and confirmation
Type or paste a complete value, and select date segments with the mouse or Left / Right. Enter commits valid input; Escape discards the current edit. Invalid or incomplete input reverts to the committed value when focus leaves the whole picker. Alt + ArrowDown moves focus into the panel.
Date and time-only modes do not require confirmation by default; valid changes may commit when focus leaves. With needConfirm, unconfirmed edits are discarded on dismissal. Clearing and presets still commit directly.
API
DatePicker API
The main table includes props for different picker modes: format, parse, presets, minDate / maxDate and calendar display props apply to calendar modes; minTime / maxTime apply to time-only mode. In datetime mode, disabledTime also receives the current Date.
Other native input attributes and aria-* target the input; className / style target the wrapper. See PopupOptions for shared popup configuration.
SingleDatePicker API
Value and callback types for calendar modes; see the main table for shared props.
DatePreset
Preset entries used by presets. T is Date for a single value or a date tuple for a range. Functions must be synchronous, free of side effects and safe to evaluate repeatedly.
TimePickerMode API
Props and callbacks for picker="time"; values always use 24-hour strings.
TimeParts
Time parts passed to disabledTime.