Date Picker `<mv-date-picker>`

日期选择器：一个输入框样式的触发器，显示格式化后的日期（包括日期范围），弹出层中是日历，带有“Today”、“Last 7 days”…等预设，以及用于日期时间值的可选时间行；支持表单关联。

分类	表单
类型	Web Component（`<mv-date-picker>`）
状态	稳定版
同时安装	calendar, time-picker
Keywords	date-picker, datepicker, date, range, presets, popover, datetime, date-time, form-associated

When to use

A form needs a single date, like a birth date or delivery day, without taking permanent space
A date range such as a booking stay or a report period must be picked in a compact trigger
Analytics filters need quick presets like Today or Last 7 days next to a calendar
A pickup, meeting or deadline needs a day and a time together in one field

Avoid when

The calendar should stay visible on the page as part of the layout → use Calendar instead
A touch-first flow picks a time or date by spinning columns, iOS style → use Wheel Picker instead
The date is far in the past and known by heart, like a birth year; plain typed fields are faster

安装

node scripts/add.mjs date-picker --out ./src/marvelous

使用 Marvelous UI MCP 服务器的 AI 智能体：install_components({ slugs: ["date-picker"], target_dir: "<absolute path>/src/marvelous", framework: "react" })。

复制的文件（含依赖）：tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/motion.js, components/calendar/calendar.js, components/calendar/calendar.css, core/dismiss.js, core/focus.js, core/form.js, core/position.js, components/time-picker/time-picker.js, components/time-picker/time-picker.css, components/date-picker/date-picker.js, components/date-picker/date-picker.css。

用法

标准标记，可在此基础上通过属性、data-* 和 CSS 变量进行定制：

<form id="date-picker-demo-form" style="display:flex;flex-wrap:wrap;gap:1.25rem;justify-content:center;align-items:flex-start">
  <div style="display:grid;gap:.4rem">
    <label for="date-picker-demo-delivery" style="font-size:.875rem;font-weight:500">Delivery date</label>
    <mv-date-picker id="date-picker-demo-delivery" name="delivery" min="2026-09-23" disable-weekends clearable presets placeholder="Pick a business day"></mv-date-picker>
  </div>
  <div style="display:grid;gap:.4rem">
    <label for="date-picker-demo-period" style="font-size:.875rem;font-weight:500">Report period</label>
    <mv-date-picker id="date-picker-demo-period" name="period" mode="range" presets value="2026-09-01/2026-09-22" format="long" style="--mv-date-picker-width:19rem"></mv-date-picker>
  </div>
  <div style="display:grid;gap:.4rem">
    <label for="date-picker-demo-pickup" style="font-size:.875rem;font-weight:500">Airport pickup</label>
    <mv-date-picker id="date-picker-demo-pickup" name="pickup" time time-step="30" time-min="06:00" time-max="22:00" min="2026-09-23" value="2026-10-02T14:30" style="--mv-date-picker-width:15rem"></mv-date-picker>
  </div>
</form>

API

Attributes

Name	类型	Default	Description
`mode`	single \| range \| multiple	`single`	Selection type (forwarded to the calendar).
`value`	string		Initial ISO value (“2026-09-22” or “2026-09-01/2026-09-22”).
`name`	string		Form field name (ISO value).
`placeholder`	string	`Pick a date`	Text shown when nothing is selected.
`format`	short \| medium \| long \| full	`medium`	Intl style of the displayed date (ranges via formatRange: “Sep 1-22, 2026”).
`presets`	boolean		Shows the default presets column (depends on the mode).
`clearable`	boolean		Button to clear the date.
`required`	boolean		Native validation; a range must be complete.
`disabled`	boolean		Disables the trigger.
`invalid`	boolean		Error style + aria-invalid.
`placement`	bottom-start \| top-start…	`bottom-start`	Popover placement (flipped when there is no room).
`min / max / disabled-dates / disable-weekends / months / locale / week-start / today`	-		Forwarded as-is to `<mv-calendar>`.
`time`	boolean		Date and time mode (single mode only): a time field and a Done button sit under the calendar and the value becomes “2026-10-02T14:30”, like datetime-local. Picking a day then moves to the time; Done, Enter in the time, Escape or a click outside closes.
`time-step / time-min / time-max / hour-cycle / seconds`	-		Time mode: forwarded to the inner `<mv-time-picker>` as step, min, max, hour-cycle and seconds (with seconds the value is “…T14:30:00”).
`label`	string		Accessible name without a `<label for>`.
`data-size`	sm \| lg		Trigger height.

Properties

Name	类型	Description
`value`	string	ISO value (also accepts a Date). In time mode “YYYY-MM-DDTHH:MM”, or “” until both the day and the time are set.
`valueAsDate`	Date \| null	First date (with its time in time mode).
`range`	{ start, end }	Range bounds.
`presetList`	Array<{ label, value: string \| (today: Date) => string }>	Custom presets (shown even without the presets attribute).
`calendar`	MvCalendar	Inner calendar (isDateDisabled, goTo…).
`isOpen`	boolean	Whether the popover is open.
`timePicker`	MvTimePicker \| null	Inner time field in time mode.
`strings`	object	Time mode labels and messages: time, done, placeholderDateTime, missingDateTime, missingTime.

Methods

Name	Description
`open() / close({ focus })`	Opens or closes the popover.
`clear()`	Clears the value.
`checkValidity() / reportValidity()`	Native validation.

Events

Name	Description
`mv-change`	detail: { value, date, start, end, complete, preset? }; in time mode also time (“14:30”), and date carries the time.
`mv-open / mv-close`	Popover opened and closed.

CSS classes

Name	Description
`mv-date-picker-trigger / -value / -clear / -popup / -presets / -preset`	Generated parts.
`mv-date-picker-main / -time / -time-label / -done`	Time mode parts: calendar and time column, time row, its label and the Done button.

CSS variables

Name	Default	Description
`--mv-date-picker-width`	`16rem (18rem for ranges)`	Trigger width.
`--mv-date-picker-radius`	`var(--mv-radius-md)`	Trigger radius.

Accessibility

<button> trigger with aria-haspopup=dialog and aria-expanded, named by the <label for> + the displayed value. The popover is a labeled non-modal role=dialog; on open, focus moves to the calendar's active day (full APG grid), Escape or picking a date/range closes it and returns focus to the trigger; tabbing out also closes it. ↓ on the trigger opens it. Presets are aria-pressed buttons. In time mode the time field follows the calendar in the tab order (its segments are spinbuttons), then the Done button.