DatePicker
date-pickerSelects a date from an input-triggered calendar popup.
Usage
Basic usage
Click the trigger to pop up a single-month calendar, select a day to submit and close. The external value is ISO date string YYYY-MM-DD.
<DatePicker defaultValue="2026-06-08" />Select month / select year
picker determines the particle size and value shape: month → YYYY-MM, year → YYYY. The panel title can be clicked to scroll up to the month/year view layer by layer.
<DatePicker picker="month" defaultValue="2026-06" />
<DatePicker picker="year" defaultValue="2026" />Limited range + disabled weekends
minDate / maxDate frame the optional range, and disabledDate further prohibits selection on a daily basis.
<DatePicker
defaultValue="2026-06-10"
minDate="2026-06-01"
maxDate="2026-06-30"
disabledDate={(iso) => {
const day = new Date(iso + "T00:00:00").getDay();
return day === 0 || day === 6;
}}
/>Custom display format
displayFormat Only changes the display on the trigger, and the shape of the external value remains unchanged.
<DatePicker defaultValue="2026-06-08" displayFormat="MMM D, YYYY" />Disabled / Read Only
disabled is grayed out and cannot be opened; readOnly can see the panel but cannot select it.
<DatePicker defaultValue="2026-06-08" disabled />
<DatePicker defaultValue="2026-06-08" readOnly />When to use
Use DatePicker to select a date, month, or year in a form. Its trigger opens a Popover containing the Calendar panel, so both components share the same drill-down and disabled-date behavior.
Use Calendar directly for an always-visible panel, DateRangePicker for a range, or DateTimePicker when the user also selects a time.
Before 0.15.0, this component was namedDateField, while a separate MUI X bridge used theDatePickername. That bridge and the_muidirectory have been removed;DatePickernow refers only to this dependency-free HulianUI implementation.
Import
import { DatePicker } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| value | string | null | — | controlled value. Shape varies with picker: "YYYY-MM-DD" / "YYYY-MM" / "YYYY" |
| defaultValue | string | null | — | Uncontrolled initial value, the shape is the same as above |
| picker | "date" | "month" | "year" | "date" | Select the granularity and determine the value shape and panel starting layer |
| minDate | string | — | Earliest selectable date as any parseable date string; normalized internally. |
| maxDate | string | — | Latest selectable date. |
| disabledDate | (isoDate: string) => boolean | — | Determines whether a date is disabled. The argument is always "YYYY-MM-DD"; month/year pickers pass the first day of that month/year. |
| placeholder | string | Follows picker | Trigger placeholder. |
| displayFormat | string | Follows picker | Day.js format string for the trigger. Affects display only and does not change the external value shape. |
| clearable | boolean | true | Shows a clear button when a value exists and the component is neither disabled nor read-only. |
| showToday | boolean | true | Shows the Today, This Month, or This Year shortcut at the bottom. |
| disabled | boolean | false | Disables the trigger and prevents the panel from opening. |
| readOnly | boolean | false | Allows viewing the panel but prevents selection. |
| aria-label | string | — | Accessible trigger name when no visible label is present. |
| className | string | — | Additional class name for the trigger's outer container. |
Events
| Event | Type | Description |
|---|---|---|
| onValueChange | (value: string | null) => void | Select/clear callback; clear callback null |
Localization
When placeholder is omitted, the date, month, and year placeholders and the
clear-button label follow the nearest ConfigProvider locale; enUS uses
“Select date,” “Select month,” and “Select year.” An explicit placeholder
always wins. A legacy custom locale with no components.datePicker, or with
only its older clear field, keeps the original Chinese fallback placeholders.
Usage guidelines
- Values are fixed-width strings, not `Date` objects. With
"YYYY-MM-DD", lexical order matches chronological order, so ranges can be compared as strings. This also avoids timezone boundary errors such asnew Date("2026-06-08").toISOString()producing the previous date in UTC+8. Convert explicitly if the application needs aDate. - `picker` changes the value shape. Switching from
datetomonthmeans an existing"2026-06-08"value is parsed and then emitted as"2026-06"after month selection. Migrate existing state deliberately when changing granularity; the component does not rewrite application data automatically. displayFormatchanges presentation only. Usepickerto change the external value shape.- At
dategranularity,disabledDateruns once per visible day, typically 42 times per panel. Keep it a pure, inexpensive calculation: do not issue requests or repeatedly allocate heavy objects. Month and year pickers call it only for the first day of each month/year, so the rule is necessarily coarser. - Clicking the panel title moves upward through date → month → year.
pickerdetermines which level submits a value, so choosing a year or month whilepicker="date"only drills down; it does not emit a final selection. - When migrating from the pre-0.15.0 MUI
DatePicker, note that the value format changed from a full ISO timestamp to a fixed-width date string. The oldviewsandopenToprops are consolidated intopicker, whilelabelis replaced byplaceholderplusaria-label.
Related
Calendar · DateRangePicker · DateTimePicker · TimePicker · TimeField · ColorField
Playground
<DatePicker
value={date}
onValueChange={setDate}
/>