@choice-ui
DocsComponentsTokens

YearCalendar

A calendar component for date selection with support for single, range, and multiple date picking

Storybook@choice-ui/calendarView Source

Installation

Terminal
pnpm add @choice-ui/calendar

Import

Component.tsx
import { type MonthCalendarProps, MonthCalendar, DateInput, DateRangeInput, type TimeCalendarProps, TimeCalendar, TimeInput, TimeRangeInput, type QuarterCalendarProps, QuarterCalendar, type YearCalendarProps, YearCalendar, dateUtils, generateWeekdayNames, generateCalendarDays, formatMonthTitle, calculateWeekNumbers, inferSelectionMode, inferMonthFromValue, isCalendarValueEqual, LOCALE_MAP, resolveLocale, getSupportedLocales, isChineseLocale, type DateComparisonMode, type DateParts, createTimeZoneContext, isSameDayInTimeZone, isSameMonthInTimeZone, isSameYearInTimeZone, isSameWeekInTimeZone, isTodayInTimeZone, isWithinRange, getDateParts, getDateKey, areDatesEqual, clearTimeZoneCache, parseMonthName, englishMonths, chineseMonths, validateDateRange, validateTimeRange, isValidDateExists, getLastDayOfMonth, smartCorrectDate, smartCorrectYear, quickValidateDate, handleShortcuts, parseRelativeDate, parseExtendedRelativeDate, parseNaturalLanguage, getLocaleKey, parseEnglishDate, getLocale, detectDateFormat, type ParseResult, type DetailedParseResult, type ParseOptions, parseDate, parseDate, parseDate, getPredictionInfo, tryRelaxedParsing, smartParseDate, parseDate, tryRelaxedParsing, smartParseDate, getPredictionInfo, type ParseOptions, type ParseResult, type DetailedParseResult, getEnhancedPrediction, type PredictionResult, validateDateRange, validateTimeRange, isValidDateExists, smartCorrectDate, smartCorrectYear, quickValidateDate, getLastDayOfMonth, getLocale, detectDateFormat, parseMonthName, parseEnglishDate, parseRelativeDate, parseExtendedRelativeDate, parseNaturalLanguage, getLocaleKey, handleShortcuts, extractDigits, convertTwoDigitYear, isValidMonthDay, canBeMonthDay, isReasonableYear, type NumericParseResult, parseYYMMDD, parseYYYYMMDD, parse3Digits, yearUtils, quarterUtils, getQuarterMonths, createQuarter, getCurrentQuarter, getYearQuarters, isQuarterEqual, formatQuarter, getQuarterDateRange, dateToTimeString, timeStringToDate, normalizeTimeValue, smartParseTimeValue, tryRelaxedTimeParsing, createTimeValue, timeToDate, dateToTime, formatTimeValue, formatHourValue, formatMinuteValue, generateHourOptions, generateMinuteOptions, isTimeEqual, findClosestValidTime, generateTimeOptions, createTimeToday, defaultLocaleMap, naturalLanguageMap, relativeDatePatterns, commonDateFormats, commonTimeFormats, parserConfig, parseCache, useDateInput, useTimeInput, type BaseYearProps, type YearItem, type YearLayoutProps, type YearNavigationProps, type BaseQuarterProps, type Quarter, type QuarterItem, type QuarterLayoutProps, type QuarterNavigationProps, type BaseCalendarProps, type CalendarValue, type CalendarState, type CalendarLayoutProps, type BaseDateProps, type DateInputValue, type DateDataFormat, type DateRange, type DateParserOptions, type DateInteractionProps, type BaseTimeProps, type Time, type TimeInputValue, type TimeDataFormat, type TimeParserOptions, type TimeLayout, type TimeInteractionProps, type TimeOptionItem, type SmartInputOptions, type StepProps, type NaturalLanguageMap, type RelativeDatePattern } from "@choice-ui/calendar"

Basic

Default: Shows the basic YearCalendar with standard configuration.
- Demonstrates year selection with 12 years displayed in a grid. - Shows both light and dark theme variants side by side. - Uses current year as the selected value and reference point.

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
Selected year: 2026

With Range

WithRange: Demonstrates YearCalendar with year range restrictions.
- Shows how to limit selectable years to a specific range (±5 years from current). - Displays navigation boundaries and how they affect user interaction. - Useful for applications with relevant time period constraints.

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
Selected year: 2026

With Disabled Years

WithDisabledYears: Demonstrates selective year disabling functionality.
- Shows how to disable specific years (2 years ago, 1 year ago, 1 year ahead). - Displays disabled years with visual indicators and prevented interaction. - Useful for restricting selection based on data availability or business rules.

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
Selected year: 2026

Different Count

DifferentCount: Demonstrates customizable year count display.
- Shows 9 years instead of the default 12 years in the grid. - Displays how year count affects the grid layout and navigation. - Useful for compact displays or when fewer years are needed.

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
Selected year: 2026

Disabled

Disabled: Demonstrates the completely disabled state of YearCalendar.
- Shows how the entire component appears and behaves when disabled. - Displays proper disabled styling and interaction prevention. - Useful for readOnly scenarios or when year selection is not applicable.

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
Selected year: 2026

Custom Start Year

CustomStartYear: Demonstrates custom starting year configuration.
- Shows year selection starting from 2020 with 15 years displayed. - Displays how to control the year range and starting point. - Useful for historical data selection or specific year range requirements.

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
Selected year: 2026

Read Only

ReadOnly: Demonstrates the YearCalendar component in readOnly mode.
- Prevents value changes while allowing focus and navigation - Maintains normal visual appearance (unlike disabled) - Useful for displaying non-editable year information
Current Value:
2024
Change Count:
0

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031

2020 - 2031

2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
💡 Try clicking years on the readonly calendar - the value should not change and the change count should remain at 0. Only the normal calendar will change the value.

API reference

MonthCalendarTypeDefault
className
string
|
undefined
 -
currentMonth
Date
|
undefined
 -
dateComparisonMode
undefined
|
"exact-time"
|
"date-only"
 -
defaultValue
CalendarValue
|
undefined
 -
disabledDates
Date[]
|
undefined
 -
fixedGrid
boolean
|
undefined
 -
highlightDates
Date[]
|
undefined
 -
highlightToday
boolean
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxDate
Date
|
undefined
 -
minDate
Date
|
undefined
 -
onChange
((value: CalendarValue) => void)
|
undefined
 -
onMonthChange
((month: Date) => void)
|
undefined
 -
readOnly
boolean
|
undefined
 -
selectionMode
undefined
|
"single"
|
"multiple"
|
"range"
 -
showOutsideDays
boolean
|
undefined
 -
showWeekNumbers
boolean
|
undefined
 -
timeZone
string
|
undefined
 -
value
CalendarValue
|
undefined
 -
weekStartsOn
undefined
|
0
|
1
|
2
|
3
|
4
|
5
|
6
 -
weekdayNames
string[]
|
undefined
 -
direction
undefined
|
"horizontal"
|
"vertical"
 -
variant
undefined
|
"default"
|
"dark"
 -
DateInputValueTypeDefault
value
Date
|
null
|
undefined
 -
onChange
((date: Date
|
null) => void)
|
undefined
 -
format
string
|
undefined
 -
size
undefined
|
"default"
|
"large"
 -
selected
boolean
|
undefined
 -
className
string
|
undefined
 -
focusSelection
undefined
|
"none"
|
"all"
|
"end"
 -
onIsEditingChange
((isEditing: boolean) => void)
|
undefined
 -
variant
undefined
|
"default"
|
"light"
|
"dark"
|
"reset"
 -
enableCache
boolean
|
undefined
true
enableKeyboardNavigation
boolean
|
undefined
true
enablePrediction
boolean
|
undefined
false
enableProfiling
boolean
|
undefined
false
locale
string
|
Locale
|
undefined
 -
maxDate
Date
|
undefined
 -
minDate
Date
|
undefined
 -
onEnterKeyDown
(() => void)
|
undefined
 -
prefixElement
ReactNode -
suffixElement
ReactNode -
DateRangeInputTypeDefault
endDisabled
boolean
|
undefined
 -
endPlaceholder
string
|
undefined
 -
endSuffixElement
ReactNode -
endValue
Date
|
null
|
undefined
 -
format
string
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxDate
Date
|
undefined
 -
minDate
Date
|
undefined
 -
onEndChange
((date: Date
|
null) => void)
|
undefined
 -
onEndFocus
(() => void)
|
undefined
 -
onEnterKeyDown
(() => void)
|
undefined
 -
onStartChange
((date: Date
|
null) => void)
|
undefined
 -
onStartFocus
(() => void)
|
undefined
 -
rangePrecision
number
|
undefined
1 - Minimum unit is 1 day
startDisabled
boolean
|
undefined
 -
startPlaceholder
string
|
undefined
 -
startSuffixElement
ReactNode -
startValue
Date
|
null
|
undefined
 -
size
undefined
|
"default"
|
"large"
 -
selected
boolean
|
undefined
 -
className
string
|
undefined
 -
focusSelection
undefined
|
"none"
|
"all"
|
"end"
 -
onIsEditingChange
((isEditing: boolean) => void)
|
undefined
 -
variant
undefined
|
"default"
|
"light"
|
"dark"
|
"reset"
 -
TimeCalendarTypeDefault
className
string
|
undefined
 -
hourStep
number
|
undefined
 -
minuteStep
number
|
undefined
 -
open
boolean
|
undefined
 -
onOpenChange
((open: boolean) => void)
|
undefined
 -
closeOnSelect
boolean
|
undefined
 -
triggerRef
RefObject<HTMLElement>
|
undefined
 -
triggerSelector
string
|
undefined
 -
defaultValue
Date
|
null
|
undefined
 -
disabled
boolean
|
undefined
 -
format
string
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxTime
Date
|
undefined
 -
minTime
Date
|
undefined
 -
onChange
((time: Date
|
null) => void)
|
undefined
 -
readOnly
boolean
|
undefined
 -
value
Date
|
null
|
undefined
 -
metaStep
number
|
undefined
 -
shiftStep
number
|
undefined
 -
step
number
|
undefined
 -
offset
number
|
undefined
 -
placement
undefined
|
"top"
|
"right"
|
"bottom"
|
"left"
|
"top-start"
|
"top-end"
|
"right-start"
|
"right-end"
|
"bottom-start"
|
"bottom-end"
|
"left-start"
|
"left-end"
 -
matchTriggerWidth
boolean
|
undefined
 -
variant
undefined
|
"default"
|
"light"
|
"reset"
 -
TimeInputValueTypeDefault
value
Date
|
null
|
undefined
 -
onChange
((time: Date
|
null) => void)
|
undefined
 -
format
string
|
undefined
 -
defaultValue
Date
|
null
|
undefined
 -
step
number
|
undefined
 -
size
undefined
|
"default"
|
"large"
 -
selected
boolean
|
undefined
 -
className
string
|
undefined
 -
focusSelection
undefined
|
"none"
|
"all"
|
"end"
 -
onIsEditingChange
((isEditing: boolean) => void)
|
undefined
 -
variant
undefined
|
"default"
|
"light"
|
"dark"
|
"reset"
 -
prefixElement
ReactNode -
suffixElement
ReactNode -
locale
string
|
Locale
|
undefined
 -
maxTime
Date
|
undefined
 -
minTime
Date
|
undefined
 -
metaStep
number
|
undefined
 -
shiftStep
number
|
undefined
 -
enableCache
boolean
|
undefined
 -
enableKeyboardNavigation
boolean
|
undefined
 -
enableProfiling
boolean
|
undefined
 -
onEnterKeyDown
(() => void)
|
undefined
 -
TimeRangeInputTypeDefault
endDisabled
boolean
|
undefined
 -
endPlaceholder
string
|
undefined
 -
endSuffixElement
ReactNode -
endValue
Date
|
null
|
undefined
 -
format
string
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxTime
Date
|
undefined
 -
minTime
Date
|
undefined
 -
onEndChange
((time: Date
|
null) => void)
|
undefined
 -
onEndFocus
(() => void)
|
undefined
 -
onEnterKeyDown
(() => void)
|
undefined
 -
onStartChange
((time: Date
|
null) => void)
|
undefined
 -
onStartFocus
(() => void)
|
undefined
 -
startDisabled
boolean
|
undefined
 -
startPlaceholder
string
|
undefined
 -
startSuffixElement
ReactNode -
startValue
Date
|
null
|
undefined
 -
size
undefined
|
"default"
|
"large"
 -
selected
boolean
|
undefined
 -
className
string
|
undefined
 -
focusSelection
undefined
|
"none"
|
"all"
|
"end"
 -
onIsEditingChange
((isEditing: boolean) => void)
|
undefined
 -
variant
undefined
|
"default"
|
"light"
|
"dark"
|
"reset"
 -
QuarterCalendarTypeDefault
currentYear
number
|
undefined
 -
defaultValue
Quarter
|
undefined
 -
disabled
boolean
|
undefined
 -
disabledQuarters
{ quarter: number; year: number; }[]
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxYear
number
|
undefined
 -
minYear
number
|
undefined
 -
onChange
((quarter: Quarter
|
null) => void)
|
undefined
 -
readOnly
boolean
|
undefined
 -
startYear
number
|
undefined
 -
value
Quarter
|
null
|
undefined
 -
onNavigate
((direction: "prev"
|
"next", newYear: number) => void)
|
undefined
 -
className
string
|
undefined
 -
variant
undefined
|
"default"
|
"dark"
 -
YearCalendarTypeDefault
currentYear
Date
|
undefined
 -
defaultValue
Date
|
undefined
 -
disabled
boolean
|
undefined
 -
disabledYears
Date[]
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxYear
Date
|
undefined
 -
minYear
Date
|
undefined
 -
onChange
((year: Date
|
null) => void)
|
undefined
 -
readOnly
boolean
|
undefined
 -
startYear
Date
|
undefined
 -
value
Date
|
null
|
undefined
 -
yearCount
number
|
undefined
 -
onNavigate
((direction: "prev"
|
"next", newStartYear: Date) => void)
|
undefined
 -
className
string
|
undefined
 -
variant
undefined
|
"default"
|
"dark"
 -
inferSelectionModeTypeDefault
end
Date -
start
Date -
inferMonthFromValueTypeDefault
end
Date -
start
Date -
formatQuarterTypeDefault
label
string -
months
string[] -
quarter
1
|
2
|
3
|
4
 -
year
number -
getQuarterDateRangeTypeDefault
label
string -
months
string[] -
quarter
1
|
2
|
3
|
4
 -
year
number -
timeToDateTypeDefault
hour
number -
minute
number -
useDateInputTypeDefault
onPressEnd
(((event: PressEvent) => void) & ((e: PointerEvent) => void))
|
undefined
 -
onPressStart
(((event: PressEvent) => void) & ((e: PointerEvent) => void))
|
undefined
 -
readOnly
boolean
|
undefined
 -
ref
Ref<HTMLInputElement>
|
undefined
 -
defaultValue
Date
|
null
|
undefined
 -
disabled
boolean
|
undefined
 -
format
string
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxDate
Date
|
undefined
 -
minDate
Date
|
undefined
 -
onChange
((date: Date
|
null) => void)
|
undefined
 -
value
Date
|
null
|
undefined
 -
metaStep
number
|
undefined
 -
shiftStep
number
|
undefined
 -
step
number
|
undefined
 -
enableCache
boolean
|
undefined
 -
enableKeyboardNavigation
boolean
|
undefined
 -
enablePrediction
boolean
|
undefined
 -
enableProfiling
boolean
|
undefined
 -
onEnterKeyDown
(() => void)
|
undefined
 -
useTimeInputTypeDefault
onPressEnd
(((event: PressEvent) => void) & ((e: PointerEvent) => void))
|
undefined
 -
onPressStart
(((event: PressEvent) => void) & ((e: PointerEvent) => void))
|
undefined
 -
readOnly
boolean
|
undefined
 -
ref
Ref<HTMLInputElement>
|
undefined
 -
defaultValue
Date
|
null
|
undefined
 -
disabled
boolean
|
undefined
 -
format
string
|
undefined
 -
locale
string
|
Locale
|
undefined
 -
maxTime
Date
|
undefined
 -
minTime
Date
|
undefined
 -
onChange
((time: Date
|
null) => void)
|
undefined
 -
value
Date
|
null
|
undefined
 -
metaStep
number
|
undefined
 -
shiftStep
number
|
undefined
 -
step
number
|
undefined
 -
enableCache
boolean
|
undefined
 -
enableKeyboardNavigation
boolean
|
undefined
 -
enableProfiling
boolean
|
undefined
 -
onEnterKeyDown
(() => void)
|
undefined
 -