@choice-ui
DocsComponentsTokens

QuarterCalendar

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 QuarterCalendar usage with standard configuration.
- Demonstrates quarter selection with both light and dark variants side by side. - Uses English locale and current year as defaults. - Provides a foundation for quarter selection implementation.

1970

1970

Selected quarter: 2026年 一季度

With Range

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

1970

1970

Selected quarter: 2026年 一季度

With Disabled Quarters

WithDisabledQuarters: Demonstrates selective quarter disabling functionality.
- Shows how to disable specific quarters (Q1 and Q3 in this example). - Displays visual and functional differences for disabled quarters. - Useful for restricting selection based on business rules or data availability.

1970

1970

Selected quarter: 2026年 一季度

Disabled

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

1970

1970

Selected quarter: 2026年 一季度

With Selected Quarter

WithSelectedQuarter: Demonstrates QuarterCalendar with a pre-selected quarter.
- Shows Q2 as initially selected with Chinese locale formatting. - Displays how selected state is visually represented and maintained. - Useful for forms or interfaces that need default quarter selections.

1970

1970

Selected quarter: 2026年 一季度

Dark Variant

DarkVariant: Demonstrates the dark theme styling of QuarterCalendar.
- Shows the component optimized for dark backgrounds and themes. - Displays proper contrast and accessibility in dark mode. - Useful for applications with dark UI themes or night mode functionality.

1970

1970

Selected quarter: 2026年 一季度

Comparison

Comparison: Demonstrates side-by-side comparison of Chinese and English locales.
- Shows how quarter labels and formatting differ between languages. - Displays independent selection states for each locale variant. - Useful for understanding localization differences and testing scenarios.

Chinese

1970

Selected quarter: 2026年 一季度

English

1970

Selected quarter: 2026年 Q1

Multi Language

MultiLanguage: Demonstrates comprehensive internationalization support.
- Shows QuarterCalendar in 6 different languages (Chinese, English, Japanese, Korean, French, German). - Displays locale-specific quarter formatting and labeling. - Useful for testing international compatibility and understanding localization features.

中文

1970

Selected quarter: 2026年 一季度

English

1970

Selected quarter: 2026年 Q1

日本語

1970

Selected quarter: 2026年 Q1

한국어

1970

Selected quarter: 2026年 Q1

Français

1970

Selected quarter: 2026年 Q1

Deutsch

1970

Selected quarter: 2026年 Q1

Read Only

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

1970

1970

💡 Try clicking quarters 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
 -