Protected Readonly_ReadonlycalendarReadonlycycle60-year cycle number (1-based).
The Chinese calendar counts years in repeating 60-year blocks. Cycle 1 starts at the epoch year of the calendar variant:
Example: Cycle 78 corresponds to 1984-2043 CE (Chinese calendar).
ReadonlydayDay of month (1-30). Lunar months are 29 or 30 days long.
Use LunarDate.daysInMonth() to determine the actual length of a given month.
ReadonlyleapWhether this is a leap month (闰月).
Leap months are inserted to keep the lunar calendar aligned with solar terms.
A leap month has the same number as the preceding month but with leap=true.
For example, 2023 has a leap second month: { month: 2, leap: true } = 闰二月.
ReadonlymonthLunar month (1-12). Month 1 is 正月 (the first month, starting at Spring Festival).
Unlike the Gregorian calendar, lunar months are either 29 or 30 days long, determined by astronomical new moon observations.
ReadonlyyearYear within the 60-year cycle (1-60).
Year 1 = 甲子年, Year 2 = 乙丑年, ..., Year 60 = 癸亥年. The GanZhi (干支) is derived directly from this value:
gan = (year - 1) % 10 (Heavenly Stem index)zhi = (year - 1) % 12 (Earthly Branch index)Day GanZhi string, e.g. "甲子"
Day GanZhi pair
Get festivals on this date in simplified Chinese
Full GanZhi info
Gregorian year in Chinese numerals (〇 style), e.g. "二〇二五"
Gregorian year in Chinese numerals (零 style), e.g. "二零二五"
Month GanZhi string, e.g. "丙寅"
Month GanZhi pair
Weekday number (0=Sunday, 1=Monday, ..., 6=Saturday)
Weekday full name in simplified Chinese, e.g. "星期六"
Weekday short name in simplified Chinese, e.g. "六"
Year GanZhi string, e.g. "甲辰"
Year GanZhi pair
Zodiac animal in simplified Chinese
Zodiac emoji
Zodiac index (0-11)
Protected_Get the raw LunarDateValue
Add days to this date, returning a new instance
Works by converting to Gregorian, adding days, then converting back. This ensures correct handling of month/year boundaries.
Number of days to add (negative to subtract)
New LunarDate instance
Add Gregorian months to this date, returning a new instance
Works on the Gregorian calendar: adds months and adjusts the year if necessary. If the resulting day exceeds the month's length, it is clamped to the last day of the month.
Number of months to add (negative to subtract)
New LunarDate instance
Add Gregorian years to this date, returning a new instance
If the resulting date is invalid (e.g., Feb 29 on a non-leap year), the day is clamped to the last day of the month.
Number of years to add (negative to subtract)
New LunarDate instance
Get the number of days in this lunar month
A lunar month is either 29 days (small month / 小月) or 30 days (big month / 大月). Calculated by converting to Gregorian and comparing the day 1 of this month and the day 1 of the next month.
29 or 30
Get the number of days between this date and another
Returns a positive number if this date is after the other, negative if before, and zero if they are the same day.
The other date to compare with
Number of days difference (this - other)
Format with a custom pattern (supports all tokens including Gregorian and weekday)
Format pattern string (see PATTERNS and FormatToken)
Locale code (default: 'zh-CN')
Formatted string
Full format with locale support
Locale code (default: 'zh-CN')
Formatted string like "甲辰龙年 五月初六" (zh-CN) or "甲辰龍年 五月初六" (zh-TW)
GanZhi (干支) format: year month day pillars
Locale code (default: 'zh-CN')
Formatted string like "甲辰年 庚午月 甲寅日" (zh-CN),
"甲辰년 경오월 갑인일" (ko-KR), or "Năm 甲辰 Tháng 庚午 Ngày 甲寅" (vi-VN)
Check if this date is a solar term day, returns the name or null
Convert to JavaScript Date
Convert to JDE
Convert to plain object
Default string representation (full format)
Return a new instance with patched fields
StaticfestivalGet a festival's Gregorian date by key
Festival key (e.g., 'spring', 'mid-autumn', 'dragon-boat', 'new-year-eve')
Gregorian year
Gregorian date, or null if the key is not found
ChineseDate.festivalDate('spring', 2024) // { year: 2024, month: 2, day: 10 }
ChineseDate.festivalDate('mid-autumn', 2024) // { year: 2024, month: 9, day: 17 }
ChineseDate.festivalDate('dragon-boat', 2024) // { year: 2024, month: 6, day: 10 }
ChineseDate.festivalDate('new-year-eve', 2024) // { year: 2025, month: 1, day: 28 }
StaticfestivalsGet all festivals in a year
StaticfromCreate from a JavaScript Date object. Uses local timezone for date components.
StaticfromCreate from a Gregorian date
Gregorian year (e.g., 2024)
Month (1-12)
Day of month
LunarDate instance
StaticfromCreate from a Gregorian date string
Supports: "2025-10-11", "2025/10/11", "2025年10月11日"
StaticfromStaticfromStaticfromCreate from a LunarDateValue object
Useful for reconstructing a date from serialized data.
The lunar date value object
StaticnewGet Chinese New Year (春节) date for a Gregorian year
Gregorian year (e.g., 2024)
Gregorian date of Spring Festival
StaticparseParse a date string and create a ChineseDate instance
Auto-detects the format:
StaticqingmingGet Qingming (清明) date — the 5th solar term, typically April 4 or 5
Culturally significant as the date for 扫墓 (tomb-sweeping).
Gregorian year
Gregorian date of Qingming
StaticsolarGet a specific solar term's Gregorian date
Solar term number (1-24). 1=立春, 5=清明, 24=大寒
Gregorian year
Gregorian date of the solar term
StaticsolarGet all 24 solar terms in a year
StatictodayGet today's lunar date
Chinese calendar date (UTC+8, epoch 2636 BCE)
The standard Chinese lunar calendar used in mainland China. Uses UTC+8 timezone and the traditional epoch starting from 2636 BCE.
Key difference from other variants: Uses UTC+8, which was adopted in 1929. Before 1929, Beijing local solar time (UTC+7:45:40) was used. This library automatically handles this historical timezone change.
Example