DateTimePicker
date-time-pickerCombines calendar and time controls for a single date-time value.
Usage
Basic usage
There is a whole calendar on the left and a time column on the right. You can choose from both sides without interfering with each other. The external value is a fixed-width text YYYY-MM-DD HH:mm, in dictionary order, which is time order.
<DateTimePicker defaultValue="2026-06-08 09:30" />With seconds + step
withSeconds adds the second column; minuteStep / secondStep controls the column granularity (commonly used is 5 / 15 / 30).
<DateTimePicker withSeconds minuteStep={15} defaultValue="2026-06-08 09:30:00" />Limited range
minDateTime / maxDateTime is the boundary of **date and time as a whole**: the date part limits the calendar, and the time part only takes effect on the day that presses the boundary - the days inside the range are open 24 hours a day.
<DateTimePicker
defaultValue="2026-06-10 12:00"
minDateTime="2026-06-08 09:30"
maxDateTime="2026-06-20 18:00"
/>Custom display format
displayFormat Only changes the display on the trigger, and the shape of the external value remains unchanged.
<DateTimePicker defaultValue="2026-06-08 09:30" displayFormat="MMM D, HH:mm" />Disabled / Read Only
disabled is grayed out and cannot be opened; readOnly can see the panel but cannot select it.
<DateTimePicker defaultValue="2026-06-08 09:30" disabled />
<DateTimePicker defaultValue="2026-06-08 09:30" readOnly />When to use
Use DateTimePicker when one field must capture both a day and a time, such as a meeting, deadline, or shift boundary. The popup places Calendar on the left and time columns on the right; each side can be adjusted independently.
Use DatePicker for date only, TimePicker for column-based time selection, or TimeField for keyboard entry. Two separate fields are often easier to complete, so use the combined control only when the workflow benefits from it.
Before 0.15.0 this component bridged to MUI XDateTimePickerand required four optional peer dependencies plusMuiBridgeProvider. The current implementation is dependency-free and no longer requires that provider.
Import
import { DateTimePicker } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| value | string | null | — | Controlled fixed-width value: "YYYY-MM-DD HH:mm", or "YYYY-MM-DD HH:mm:ss" with seconds enabled. |
| defaultValue | string | null | — | Initial value when uncontrolled, using the same format as value. |
| withSeconds | boolean | false | Shows the seconds column and changes the value shape to include seconds. |
| minuteStep | number | 1 | Increment between minute options; common values are 5, 15, and 30. |
| secondStep | number | 1 | Increment between second options. |
| minDateTime | string | — | Earliest selectable date and time, inclusive. Its date limits the calendar; its time applies only on that boundary date. |
| maxDateTime | string | — | Latest selectable date and time, inclusive, with the same boundary-date behavior. |
| disabledDate | (isoDate: string) => boolean | — | Disables dates. The argument is always "YYYY-MM-DD"; this callback does not filter times. |
| placeholder | string | From ConfigProvider locale | Trigger placeholder. An explicit value overrides the locale default. |
| displayFormat | string | Display as is | Day.js format string used by the trigger. It affects presentation only; the external value format does not change. |
| clearable | boolean | true | Shows a clear button when a value exists and the control is neither disabled nor read-only. |
| showNow | boolean | true | Shows the locale-aware Now shortcut, rounded down to the configured step. |
| disabled | boolean | false | Disables the trigger and prevents the panel from opening. |
| readOnly | boolean | false | Allows the panel to open but prevents selection. |
| aria-label | string | — | Accessible name for an unlabeled trigger. |
| className | string | — | Additional class name for the outer trigger container. |
Events
| Event | Type | Description |
|---|---|---|
| onValueChange | (value: string | null) => void | Called with the selected value, or null when cleared. |
Localization
The placeholder, clear action, hour/minute/second columns, Now shortcut, and
confirmation action follow the nearest ConfigProvider locale. An explicitplaceholder takes precedence. A legacy custom locale withoutcomponents.dateTimePicker retains the original Chinese compatibility labels.
Usage guidelines
- The value is fixed-width text, not `Date` or an ISO timestamp:
"YYYY-MM-DD HH:mm", with a space between date and time. Lexical order matches chronological order without timezone conversion. Migrate full ISO timestamps when upgrading from the pre-0.15.0 MUI version. - The time portion of `minDateTime` and `maxDateTime` applies only on the boundary date. Interior dates allow the full day. For example, a minimum of June 8 at 09:30 must not disable June 9 at 00:00.
- Selecting a date does not close the popup. The user still needs to choose a time; click OK or outside the popup to close it.
- If the user selects a date without choosing a time, the component supplies
00:00, or the earliest allowed time whenminDateTimeconstrains that date. - If the user chooses a time before a date, the date defaults to today so the action produces a usable value.
disabledDatefilters whole dates only. Validate more granular rules, such as a blocked time window on certain weekdays, when the form is submitted.minuteSteplimits clickable minute options but does not validate an externalvalue. With"2026-06-08 09:07"andminuteStep={15}, 07 is absent and the minute column appears unselected.
Related
DatePicker · Calendar · TimePicker · TimeField · DateRangePicker · Scheduler
Playground
<DateTimePicker
value={dateTime}
onValueChange={setDateTime}
/>