Date Picker — `<mv-date-picker>`

Date picker: an input-style trigger showing the formatted date (ranges included) and a calendar in a popover, with presets like “Today”, “Last 7 days”…; form-associated.

Category	Forms
Type	Web Component (`<mv-date-picker>`)
Status	stable
Also installs	calendar
Keywords	date-picker, datepicker, date, range, presets, popover, 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

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

Install

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

AI agent with the Marvelous UI MCP server: install_components({ slugs: ["date-picker"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).

Files copied (dependencies included): tokens/tokens.css, core/base.css, core/dismiss.js, core/dom.js, core/element.js, core/motion.js, core/position.js, components/date-picker/date-picker.js, components/date-picker/date-picker.css, components/calendar/calendar.js, components/calendar/calendar.css.

Usage

Canonical markup — start from it and customize with attributes, data-* and CSS variables:

<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>
</form>

API

Attributes

Name	Type	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>`.
`label`	string		Accessible name without a `<label for>`.
`data-size`	sm \| lg		Trigger height.

Properties

Name	Type	Description
`value`	string	ISO value (also accepts a Date).
`valueAsDate`	Date \| null	First date.
`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.

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? }.
`mv-open / mv-close`	Popover opened and closed.

CSS classes

Name	Description
`mv-date-picker-trigger / -value / -clear / -popup / -presets / -preset`	Generated parts.

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.