DatePicker

DatePicker is a feature-rich date-time picker component that supports multiple calendar systems, theme modes, and complete internationalization functionality.

Main Features

Date Selection and Input

Basic Date Input

Format: YYYY-MM-DD, supports keyboard navigation and auto-completion

Date with Time Input

Automatically focuses on time field after date input completion

Required Validation

Real-time validation with error messages

WARNING

Input functionality is only available when calendar is set to 'gregory'

vue

<template>
  <!-- Date only -->
  <DatePicker v-model="dateOnly" />

  <!-- With time -->
  <DatePicker v-model="dateTime" :showTime="true" />

  <!-- Required validation -->
  <DatePicker v-model="requiredDate" required />
</template>

Custom Date Format and Order

The component automatically adjusts the input field order based on dateFormat, supporting various common date formats:

Year-Month-Day (YYYY-MM-DD)

Input order: Year → Month → Day

Day/Month/Year (DD/MM/YYYY)

Input order: Day → Month → Year

Month/Day/Year (MM/DD/YYYY)

Input order: Month → Day → Year

vue

<template>
  <!-- Year-Month-Day format -->
  <DatePicker v-model="date1" dateFormat="YYYY-MM-DD" />

  <!-- Day/Month/Year format -->
  <DatePicker v-model="date2" dateFormat="DD/MM/YYYY" date-separator="/" />

  <!-- Month/Day/Year format -->
  <DatePicker v-model="date3" dateFormat="MM/DD/YYYY" date-separator="/" />
</template>

Date Range Constraints

Range limit: 2025-01-01 ~ 2025-12-31

vue

<template>
  <DatePicker
    v-model="constrainedDate"
    minDate="2025-01-01"
    maxDate="2025-12-31"
  />
</template>

Inline Mode

Set inline to render only the calendar body: no trigger row (calendar icon and clear button included), no Teleport, no positioning, and no document listener that could close the calendar. Opening and closing, outside-click, Esc, focus management and positioning are entirely your container's responsibility.

Use it when the calendar belongs inside a popover, dropdown, or panel you already own. Because the calendar becomes a real descendant of your panel, your own outside-click check (panel.contains(event.target)) recognises clicks on it — without inline, clicking a day would register as a click outside your panel and close it.

vue

<template>
  <div v-if="open" ref="panel" class="my-panel">
    <DatePicker inline v-model="date" />
  </div>
</template>

Differences under inline:

showCalendarIcon / showClearButton are ignored (not rendered); call the exposed reset() or set the v-model to null to clear
No component min-width is applied — width is up to your container; the calendar caps itself at 20rem (320px)
No border, shadow, background or z-index; your container provides the surface
The panel is role="group", not a modal dialog
When disabled, the calendar is not rendered (there is no trigger to disable)
inputEnabled is ignored: it drives the trigger input field, which does not exist under inline

Props

Basic Properties

Property	Type	Default	Description
`modelValue`	`DateTimeInput`	`null`	Bound date value
`disabled`	`boolean`	`false`	Whether disabled
`required`	`boolean`	`false`	Whether required
`showClearButton`	`boolean`	`true`	Show clear button

Calendar System

Property	Type	Default	Description
`calendar`	`string`	`'gregory'`	Calendar system ('gregory', 'roc')
`locale`	`string`	`'zh-TW'`	Locale
`weekStartsOn`	`0-6`	`0`	Week start day (0=Sunday)

Date Format

Property	Type	Default	Description
`dateFormat`	`string`	`'YYYY-MM-DD'`	Date format
`dateSeparator`	`string`	`'-'`	Date separator
`outputType`	`OutputType`	`'iso'`	Output type
`useStrictISO`	`boolean`	`false`	Strict ISO format

Time Options

Property	Type	Default	Description
`showTime`	`boolean`	`false`	Show time selection
`timeFormat`	`string`	`undefined`	Time format (defaults based on enableSeconds & use24Hour)
`enableSeconds`	`boolean`	`true`	Enable seconds
`use24Hour`	`boolean`	`true`	Use 24-hour format
`customDefaultTime`	`string`	`undefined`	Custom default time

Theme Appearance

Property	Type	Default	Description
`mode`	`'light' \| 'dark' \| 'auto'`	`'auto'`	Theme mode (light / dark / follow system)
`theme`	`TailwindColor \| string`	`undefined`	Theme color — a built-in name, hex, rgb, or oklch. Defaults to the family primary (`indigo`).

Internationalization & Error Handling

Property	Type	Default	Description
`customLocaleMessages`	`LocaleMessages`	`undefined`	Custom locale messages
`customErrorMessages`	`Record<string, string>`	`{}`	Custom error messages
`useI18n`	`boolean`	`true`	Use built-in i18n
`showErrorMessage`	`boolean`	`true`	Show error messages

Input Control

Property	Type	Default	Description
`inline`	`boolean`	`false`	Render only the calendar body, without the built-in popup (see Inline Mode above)
`inputEnabled`	`boolean`	`true`	Allow input field entry (ignored when `inline`)
`placeholderOverrides`	`PlaceholderOverrides`	`{}`	Custom placeholders
`autoFocusTimeAfterDate`	`boolean`	`true`	Auto focus time input after date

PlaceholderOverrides interface:

typescript

interface PlaceholderOverrides {
  selectDate?: string; // Date selection hint text
  year?: string; // Year input placeholder
  month?: string; // Month input placeholder
  day?: string; // Day input placeholder
  hour?: string; // Hour input placeholder
  minute?: string; // Minute input placeholder
  second?: string; // Second input placeholder
}

Events

Event Name	Parameters	Description
`update:modelValue`	`(value: DateTimeInput)`	Triggered when value changes
`change`	`(value: DateTimeInput)`	Triggered when user changes value
`validation`	`(isValid: boolean, errors: Record<string, string>, errorParams?: Record<string, Record<string, any>>)`	Triggered when validation changes

Advanced Features

Multiple Calendar Systems

Gregorian Calendar

ROC Calendar

vue

<template>
  <!-- Gregorian Calendar -->
  <DatePicker v-model="gregorianDate" calendar="gregory" />

  <!-- ROC Calendar -->
  <DatePicker v-model="rocDate" calendar="roc" outputType="custom" />
</template>

TIP

For more calendar systems, see calendar

Theme Modes

Light Mode

Dark Mode

vue

<template>
  <!-- Different theme modes -->
  <DatePicker v-model="date1" mode="light" theme="blue" />
  <DatePicker v-model="date2" mode="dark" theme="emerald" />
</template>

TIP

For more theme options, see theme

Time Configuration

24-Hour Format

Output:

12-Hour Format

Output:

12-Hour Format Custom Output

Output:

Without Seconds

Custom Default Time

vue

<template>
  <!-- 24-hour format -->
  <DatePicker v-model="time24" :showTime="true" :use24Hour="true" />

  <!-- 12-hour format -->
  <DatePicker v-model="time12" :showTime="true" :use24Hour="false" />

  <!-- 12-hour format custom output -->
  <DatePicker
    v-model="time12Custom"
    :showTime="true"
    :use24Hour="false"
    outputType="custom"
    timeFormat="hh:mm:ss A"
  />

  <!-- Without seconds -->
  <DatePicker v-model="timeNoSeconds" :showTime="true" :enableSeconds="false" />

  <!-- Custom default time -->
  <DatePicker
    v-model="customTime"
    :showTime="true"
    customDefaultTime="15:30:00"
  />
</template>

Output Format Explanation

ISO Mode (Default)

outputType="iso": Outputs ISO 8601 standard format
Time portion always uses 24-hour format (e.g., 2025-06-30 14:30:00)
use24Hour parameter only affects input interface display, not output format

Custom Mode

outputType="custom": Fully customizable output format
Use timeFormat to control time output format
Example: use24Hour={false} + timeFormat="hh:mm:ss A" → outputs 2025-06-30 02:30:00 PM

use24Hour Parameter Function

✅ Controls whether time input interface shows AM/PM selector
✅ Affects output when outputType="custom" combined with timeFormat
❌ Does not change ISO format output (ISO standard is inherently 24-hour)

Output Formats

ISO Format Output

Output:

ISO Format Output (Strict Mode)

Output:

JavaScript Date Object Format

Output:

Object Format

Output:

Custom Format Output

Output:

vue

<template>
  <!-- ISO format -->
  <DatePicker v-model="isoDate" outputType="iso" />
  <!-- ISO format (strict mode) -->
  <DatePicker
    v-model="isoStrictDate"
    outputType="iso"
    :useStrictISO="true"
    :showTime="true"
  />

  <!-- Date object format -->
  <DatePicker v-model="jsDate" outputType="date" />

  <!-- Object format -->
  <DatePicker v-model="objectDate" outputType="object" />

  <!-- Custom format -->
  <DatePicker v-model="customDate" outputType="custom" dateFormat="YY/MM/DD" />
</template>

Slots

DatePicker provides multiple slots to customize calendar display and error message handling.

Custom Year Display

Custom Month Selector

Code Example

vue

<template>
  <!-- Custom year display -->
  <DatePicker v-model="date" calendar="roc">
    <template #year-display="{ yearData, isSelected }">
      <div class="custom-year-display">
        <div
          :class="['font-bold', isSelected ? 'text-white' : 'text-blue-600']"
        >
          {{ yearData.displayYear }}
        </div>
        <div v-if="yearData.showReference" class="text-xs opacity-70">
          ({{ yearData.referenceYear }})
        </div>
      </div>
    </template>
  </DatePicker>

  <!-- Custom month selector -->
  <DatePicker v-model="date">
    <template #month-selector="{ monthNames, selectedMonth, onMonthChange }">
      <div class="grid grid-cols-3 gap-1 p-2 bg-gray-50 rounded-lg">
        <button
          v-for="(month, index) in monthNames"
          :key="index"
          @click="onMonthChange(index + 1)"
          class="px-2 py-1 text-xs rounded transition-all duration-200 transform hover:scale-105"
          :class="{
            'bg-blue-500 text-white shadow-lg': selectedMonth === index + 1,
            'bg-white text-gray-600 dark:text-gray-400 hover:bg-blue-100':
              selectedMonth !== index + 1,
          }"
        >
          {{ month.slice(0, 3) }}
        </button>
      </div>
    </template>
  </DatePicker>
</template>

Error Message Slot

DatePicker also supports custom error messages, see Error Message Handling Documentation.

Available Slots List

Slot Name	Description	Slot Props
`year-display`	Custom year display	`{ yearData, isSelected }`
`month-selector`	Custom month selector	`{ monthNames, selectedMonth, onMonthChange }`
`year-selector`	Custom year selector	`{ displayYear, toggleYearSelector, showYearSelector }`
`no-years-display`	Display when no years available in year selector	`{ calendarId, locale }`
`error`	Custom error message display	`{ errors, errorParams, hasErrors }`

Note

Slot availability may vary depending on calendar system and configuration. It's recommended to test related functionality before use.

DatePicker provides various smart input features to enhance user experience:

Auto-padding and Jump

• Month input "2" auto-pads to "02" and jumps to day

• Day input "5" auto-pads to "05" and completes input

• Year input completes after full 4 digits and jumps to month

Keyboard Navigation

• → / ← Arrow keys to switch fields

• Backspace in empty field returns to previous field

• Enter completes input and validates

• Auto focus to time field after date input completion

DatePicker ​

Main Features ​

Date Selection and Input ​

Basic Date Input

Date with Time Input

Required Validation

Custom Date Format and Order ​

Year-Month-Day (YYYY-MM-DD)

Day/Month/Year (DD/MM/YYYY)

Month/Day/Year (MM/DD/YYYY)

Date Range Constraints ​

Date Range Constraints

Inline Mode ​

Props ​

Basic Properties ​

Calendar System ​

Date Format ​

Time Options ​

Theme Appearance ​

Internationalization & Error Handling ​

Input Control ​

Events ​

Advanced Features ​

Multiple Calendar Systems ​

Gregorian Calendar

ROC Calendar

Theme Modes ​

Light Mode

Dark Mode

Time Configuration ​

24-Hour Format

12-Hour Format

12-Hour Format Custom Output

Without Seconds

Custom Default Time

Output Formats ​

ISO Format Output

ISO Format Output (Strict Mode)

JavaScript Date Object Format

Object Format

Custom Format Output

Slots ​

Calendar Related Slots ​

Custom Year Display

Custom Month Selector

Error Message Slot ​

Available Slots List ​

Keyboard Navigation ​

Auto-padding and Jump

Keyboard Navigation

DatePicker

Main Features

Date Selection and Input

Custom Date Format and Order

Date Range Constraints

Inline Mode

Props

Basic Properties

Calendar System

Date Format

Time Options

Theme Appearance

Internationalization & Error Handling

Input Control

Events

Advanced Features

Multiple Calendar Systems

Theme Modes

Time Configuration

Output Formats

Slots

Calendar Related Slots

Error Message Slot

Available Slots List

Keyboard Navigation