Calendar Systems

Vue DatePicker supports multiple calendar systems, powered by the robust @internationalized/date package for internationalized date handling.

Supported Calendar Systems

Calendar System	Identifier	Region/Usage
Gregorian	`gregory`	International (Default)
Republic of China	`roc`	Taiwan
Buddhist	`buddhist`	Buddhist Countries
Japanese	`japanese`	Japan
Islamic	`islamic-civil`	Islamic Countries
Persian	`persian`	Iran
Hebrew	`hebrew`	Israel
Indian	`indian`	India
Others	`ethiopic`, `coptic` etc	Specific Regions

Registering Calendars

Since v2.0, only the Gregorian calendar is built in. Every other calendar is opt-in — register it once at app startup so unused calendars can be tree-shaken out of your bundle.

// main.ts
import {
  registerCalendar,
  rocCalendar,
  buddhistCalendar,
  japaneseCalendar,
} from "@tiaohsun/vue-datepicker";

registerCalendar(rocCalendar);
registerCalendar(buddhistCalendar);
registerCalendar(japaneseCalendar);

vue

<DatePicker v-model="date" calendar="roc" />

Using a calendar that hasn't been registered falls back to the Gregorian calendar and logs a warning in development.

Built-in Descriptors

Import	`calendar` id
`rocCalendar`	`roc`
`buddhistCalendar`	`buddhist`
`japaneseCalendar`	`japanese`
`persianCalendar`	`persian`
`hebrewCalendar`	`hebrew`
`indianCalendar`	`indian`
`copticCalendar`	`coptic`
`ethiopicCalendar`	`ethiopic`
`ethioaaCalendar`	`ethioaa`
`islamicCivilCalendar`	`islamic-civil`
`islamicTabularCalendar`	`islamic-tbla`
`islamicUmalquraCalendar`	`islamic-umalqura`

Helpers

import {
  isCalendarRegistered,
  getCalendarDescriptor,
} from "@tiaohsun/vue-datepicker";

isCalendarRegistered("roc"); // boolean
getCalendarDescriptor("roc"); // CalendarDescriptor | undefined

Basic Usage

v-model:

Use the interactive example above to experience the display effects of different calendar systems and languages.

Important Notes

Date and time input functionality only supports the gregory calendar system
Output format defaults to iso, use custom for localized formats
For advanced ROC formatting, see ROC Formatting Plugin

Year Range Limitations

Different calendar systems have their own valid year ranges:

Calendar	Min Year	Max Year	Description
Gregory	1	Current+100	Gregorian era
ROC	1912	Current+100	ROC Year 1 corresponds to 1912 CE
Buddhist	544	Current+643	Buddhist era is 543 years earlier than Gregorian
Japanese	1868	Current+100	Starting from Meiji Restoration
Islamic	622	Current+100	Islamic era
Persian	622	Current+100	Persian era
Hebrew	1	Current+3860	Hebrew era
Others	System dependent		See @internationalized/date docs

Notice

Dates outside the valid range may cause unpredictable behavior
Not all browsers fully support all calendar systems
It's recommended to test compatibility with target browsers in production
Unsupported environments will automatically fallback to Gregorian calendar

API Reference

Property	Type	Default	Description
`calendar`	`string`	`'gregory'`	Calendar system identifier
`locale`	`string`	`'zh-TW'`	Language localization setting
`output-type`	`'iso' \| 'date' \| 'object' \| 'custom'`	`'iso'`	Output format type

Calendar Systems ​

Supported Calendar Systems ​

Registering Calendars ​

Built-in Descriptors ​

Helpers ​

Basic Usage ​

Year Range Limitations ​

API Reference ​

Calendar Related Properties ​