Date Picker <mv-date-picker>

날짜 선택기입니다. 서식화된 날짜(범위 포함)를 보여 주는 입력란 형태의 트리거와 팝오버 속 캘린더, “Today”, “Last 7 days”… 같은 프리셋, 그리고 날짜와 시간 값을 위한 선택적 시간 행을 제공하며, 폼과 연동됩니다.

카테고리폼
유형Web Component (<mv-date-picker>)
상태안정
함께 설치되는 항목calendar, time-picker
Keywordsdate-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/i18n.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유형기본설명
modesingle | range | multiplesingleSelection type (forwarded to the calendar).
valuestringInitial ISO value (“2026-09-22” or “2026-09-01/2026-09-22”).
namestringForm field name (ISO value).
placeholderstringPick a dateText shown when nothing is selected.
formatshort | medium | long | fullmediumIntl style of the displayed date (ranges via formatRange: “Sep 1-22, 2026”).
presetsbooleanShows the default presets column (depends on the mode).
clearablebooleanButton to clear the date.
requiredbooleanNative validation; a range must be complete.
disabledbooleanDisables the trigger.
invalidbooleanError style + aria-invalid.
placementbottom-start | top-start…bottom-startPopover placement (flipped when there is no room).
min / max / disabled-dates / disable-weekends / months / locale / week-start / today-Forwarded as-is to <mv-calendar>. Locale: The value auto follows the page language (nearest lang); without the attribute, en-US unless the app registered the page language with setStrings() (core/i18n.js).
timebooleanDate 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”).
labelstringAccessible name without a <label for>.
data-sizesm | lgTrigger height.

Properties

Name유형설명
valuestringISO value (also accepts a Date). In time mode “YYYY-MM-DDTHH:MM”, or “” until both the day and the time are set.
valueAsDateDate | nullFirst date (with its time in time mode).
range{ start, end }Range bounds.
presetListArray<{ label, key?, value: string | (today: Date) => string }>Custom presets (shown even without the presets attribute). An optional key names the strings entry that gives the button text (the default presets use it).
calendarMvCalendarInner calendar (isDateDisabled, goTo…).
isOpenbooleanWhether the popover is open.
timePickerMvTimePicker | nullInner time field in time mode.
stringsPartial<Record<string, string | { one, other }>>Overrides for the default text (en-US): clearDate (clear button label), presets (preset group label), placeholderDate, placeholderRange and placeholderMultiple (empty trigger text and dialog label), rangeOpen (range without an end, {start}), datesSelected (multiple mode, {n}, { one, other }), missingDate and missingRange (required messages), presetToday, presetTomorrow, presetInAWeek, presetInAMonth, presetLast7Days, presetLast30Days, presetThisMonth, presetLastMonth and presetThisYear (default preset buttons; a custom preset with a key reads its text here), and for the time attribute: time, done, placeholderDateTime, missingDateTime, missingTime. The inner calendar has its own strings (key "calendar"). App-wide translations: setStrings() from core/i18n.js, under the key "date-picker". Can be set before the element is defined.

Methods

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

Events

Name설명
mv-changedetail: { value, date, start, end, complete, preset? }; in time mode also time (“14:30”), and date carries the time.
mv-open / mv-closePopover opened and closed.

CSS classes

Name설명
mv-date-picker-trigger / -value / -clear / -popup / -presets / -presetGenerated parts.
mv-date-picker-main / -time / -time-label / -doneTime mode parts: calendar and time column, time row, its label and the Done button.

CSS variables

Name기본설명
--mv-date-picker-width16rem (18rem for ranges)Trigger width.
--mv-date-picker-radiusvar(--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.

이 페이지는 AI로 번역되었습니다. 번역 문제 신고