Date Picker

Stable v1.0.2

Pick a single date or a range, by hand or from presets. Supports inline calendars, time selection, and min/max limits, built on date-fns instead of a heavier date library.

Interactive Playground

Configure selection modes (Range, Month-only), layouts (Inline), and strict formatting models in real-time.

Architecture

Selection Mode

Single Date

Picker Type Depth

Standard (Date)

Inline Render

Enable Time Input

Auto Apply

Close Popover on Select

Formatting & Parsing

Display Format (UI)

MM/dd/yyyy (US)

Model Format (Payload)

Native Date Object

Apply Range Constraints

Component State

Custom ID (id prop)

Input Label

Placeholder (overrides format)

Label Position

Top

Component Size

Small (sm)

Required

Error

Range & Presets

Show Presets Bar

Use Custom presetRanges

rangeKeys.start

rangeKeys.end

v-model Payload

Native Payload Output

null

Vessel Departure

Awaiting platform events...

Live Source Code

<DatePicker
  v-model="date"
  id="vessel-departure-date"
  label="Vessel Departure"
/>

Real-World Usage Examples

Implementation scenarios ranging from standard inputs to complex object ranges. Mobile-friendly layouts ensure smooth interactions on any device.

Voyage Schedule Range

1. Object-Based Date Range

Transforms into a side-by-side picker outputting { start: Date, end: Date }. Fully mobile-responsive.

<DatePicker
  v-model="range"
  mode="range"
  label="Voyage Schedule Range"
  showPresets
/>

Card Expiration

2. Month Picker

Locks depth to the monthly grid. Automatically returns the 1st day of the selected month.

<DatePicker
  v-model="month"
  pickerType="month"
  displayFormat="MM/yyyy"
/>

Financial Audit Year

3. Year Picker

Opens directly to the decade grid. Perfect for high-level forecasting and reporting.

<DatePicker
  v-model="year"
  pickerType="year"
  displayFormat="yyyy"
/>

Schedule Maintenance Slot

July2026

Sun

Mon

Tue

Wed

Thu

Fri

Sat

Time

4. Inline Booking & Time Selection

Permanently exposes the calendar body. Horizontal overflow logic ensures small mobile screens handle inline rendering gracefully.

<DatePicker
  v-model="time"
  inline
  enableTime
  displayFormat="MM/dd/yyyy HH:mm"
/>

API Reference

Complete specifications for properties and emitted events.

Props

Name	Type / Signature	Default	Description
v-model	any	null	The bound value. Can be a Date, String, Number, or Object depending on `mode` and `modelFormat`.
id	string	undefined	Overrides the auto-generated id applied to the underlying input element and its label.
mode	"single" \| "range"	"single"	Determines if the picker captures one date or a contiguous start/end period.
pickerType	"date" \| "month" \| "year"	"date"	Restricts selection depth. "month" picks full months, "year" picks only years.
inline	boolean	false	Renders the calendar persistently on the DOM, bypassing the popover trigger.
enableTime	boolean	false	Injects hour/minute selectors into the calendar footer (single mode only).
displayFormat	string	"MM/dd/yyyy"	The date-fns string format used for the manual text input and dropdown visuals.
modelFormat	"Date" \| "ISO" \| "timestamp" \| string	"Date"	The data type emitted to the v-model. Decouples visuals from backend payloads.
rangeKeys	object	{ start: "start", end: "end" }	Allows overriding the object keys used when mode="range".
minDate	Date \| string \| number	undefined	Disables all dates prior to this specific threshold.
maxDate	Date \| string \| number	undefined	Disables all dates after this specific threshold.
closeOnSelect	boolean	true	Automatically closes the popover upon final selection.
autoApply	boolean	true	Commits each selection immediately. Set to false to stage picks locally and require an Apply/Cancel action before the v-model updates.
showPresets	boolean	false	Displays a horizontal quick-select bar for common range periods (mode="range" only).
presetRanges	{ label: string; range: [Date, Date] }[]	undefined	Overrides the built-in Today/Yesterday/Last 7 Days preset list with a custom set of quick-select ranges.
label	string	undefined	Primary typography display above or beside the component.
labelPosition	"top" \| "left"	"top"	Alignment of the label relative to the input field.
required	boolean	false	Marks the field as required and renders an asterisk next to the label.
placeholder	string	undefined	Text shown when the input is empty. Falls back to the active displayFormat when omitted.
disabled	boolean	false	Disables user interaction and grays out the component.
size	"xs" \| "sm" \| "md" \| "lg" \| "xl"	"sm"	Component dimensions, tightly mapped to standard InputText sizing.
showClear	boolean	true	Displays an interactive "x" icon to nullify the current selection.
error	string \| boolean \| string[]	false	Injects validation error styling and displays message(s).

Events

Event Name	Payload Signature	Description
@change	(value: any)	Fired when a valid date/range is selected via calendar click or manual input.
@clear	()	Fired specifically when the "x" clear icon is clicked.
@focus	(event: FocusEvent)	Dispatched when the core text input receives focus.
@blur	(event: FocusEvent)	Dispatched when the core text input loses focus.
@apply	(value: any)	Fired when the Apply button commits a staged selection (autoApply="false" only).
@cancel	()	Fired when the Cancel button discards a staged selection (autoApply="false" only).