API Reference
Complete API documentation for React Calendar DateTime Picker components, types, and utilities.
Components
Both DtCalendar and DtPicker share most of their API. The props are organized into shared props (available in both components) and component-specific props.
Shared Props
These props are available in both DtCalendar and DtPicker:
DtPicker Only
These props are only available in DtPicker:
DtCalendar Only
These props are only available in DtCalendar:
Shared Props
These props are available in both `DtCalendar` and `DtPicker`:
| Prop | Type | Default | Description |
|---|---|---|---|
| initValue | InitValueInput | undefined | Initial value for the calendar/picker |
| onChange | (date: unknown) => void | Required | Callback function called when the final date value changes. Receives the calculated value based on type: Day for single, Range for range/week, or Multi (Day[]) for multi. Fires AFTER onDateSelect. Use this to update your application state with the final selected value. |
| type | CalendarType | 'single' | Calendar selection type |
| withTime | boolean | false | Enable time selection |
| calendarSystem | CalendarSystem | 'gregorian' | Calendar system: "gregorian" or "jalali". Also accepts shorthand aliases: "ge" for "gregorian", "ja" for "jalali" |
| showWeekend | boolean | false | Show weekend highlighting |
| todayBtn | boolean | false | Show today button |
| presetRanges | PresetRangesConfig | undefined | Preset range buttons configuration |
| constraints | CalendarConstraintsInput | undefined | Date constraints |
| calenderModalClass | string | undefined | Custom CSS class for calendar modal |
| customization | CalendarCustomization | undefined | Customization options |
| numberOfMonths | 1 | 2 | 3 | 1 | Number of months to display |
| yearListStyle | 'grid' | 'list' | 'grid' | Year list style for year selection view |
| dark | boolean | false | Enable dark theme |
| onDateSelect | (day: Day) => void | undefined | Callback fired immediately when a date is clicked. Receives the raw Day object that was clicked. Fires BEFORE onChange. Use this to track individual date clicks or intercept before the final value is calculated. Note: For range/multi types, this fires for each individual date click, while onChange receives the final calculated range/array. |
| onMonthSelect | (month: number) => void | undefined | Callback when a month is selected in month view |
| onYearSelect | (year: number) => void | undefined | Callback when a year is selected in year view |
| onViewChange | (view: 'calendar' | 'months' | 'years') => void | undefined | Callback when the view changes (calendar, months, or years) |
| onMonthNavigate | (direction: 'prev' | 'next') => void | undefined | Callback when navigating between months |
| onGoToToday | () => void | undefined | Callback when the "Today" button is clicked |
| enlargeSelectedDay | boolean | true | Enlarge selected day text in the calendar grid |
| dateFormat | string | undefined | Custom date format string for displaying dates in the input field. Supports custom separators and order. Examples: "DD/MM/YYYY", "MM-DD-YYYY", "YYYY년 MM월 DD일". Default format is YYYY/MM/DD when not specified. |
| onError | (errors: CalendarError[]) => void | undefined | Callback function called when normalization or constraint errors occur. Receives an array of error objects describing what failed (e.g., invalid initValue, invalid constraints). |
DtPicker Only
These props are only available in `DtPicker`:
| Prop | Type | Default | Description |
|---|---|---|---|
| showTimeInput | boolean | false | Show time in input field |
| clearBtn | boolean | false | Show clear button |
| isRequired | boolean | false | Make input required |
| isDisabled | boolean | false | Disable the picker |
| placeholder | string | 'Select date' | Placeholder text |
| inputClass | string | undefined | Custom CSS class for input |
| autoClose | boolean | true | Auto-close calendar after selection |
| inputId | string | undefined | Input element ID |
| triggerElement | ReactNode | undefined | Custom trigger element to replace the default input field. When provided, the input field will not be rendered. Useful for custom buttons, divs, or other elements. |
| triggerClass | string | undefined | Custom CSS class for trigger wrapper when using custom trigger element |
DtCalendar Only
These props are only available in `DtCalendar`: