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`:

Prop	Type	Default	Description
onCalenderChange	`(date: Day \| Range \| Multi \| null) => void`	`undefined`	Callback that runs when calendar value changes (requires initValue)

Types

TypeScript type definitions for React Calendar DateTime Picker components, props, and utilities.

Type Definitions

The following types are used throughout the library for type safety and better developer experience.

CalendarType

Type Definition:

type CalendarType = 'single' | 'range' | 'multi' | 'week'

CalendarLocale

Type Definition:

type CalendarLocale = 'gregorian' | 'jalali'

CalendarSystem

Type Definition:

type CalendarSystem = 'gregorian' | 'jalali' | 'ge' | 'ja'

DateInput

Type Definition:

type DateInput = Day | Date | string | number

InitValueInput

Type Definition:

type InitValueInput =
  | DateInput
  | { from: DateInput; to: DateInput }
  | DateInput[]
  | null

Day

Type Definition:

interface Day {
  year: number
  month: number
  day: number
  fullDay?: string
  hour?: number
  minute?: number
}

Range

Type Definition:

interface Range {
  from: Day
  to: Day
}

CalendarConstraintsInput

Type Definition:

interface CalendarConstraintsInput {
  maxDate?: DateInput
  minDate?: DateInput
  disabledDates?: DateInput[]
  isDateDisabled?: (date: Day) => boolean
}

CalendarClasses

Type Definition:

interface CalendarClasses {
  header?: string
  days?: string
  months?: string
  years?: string
}

CalendarIcons

Type Definition:

interface CalendarIcons {
  next?: React.ComponentType<{ className?: string }>
  previous?: React.ComponentType<{ className?: string }>
  calendar?: React.ComponentType<{ className?: string }>
}

CalendarLabels

Type Definition:

interface CalendarLabels {
  nextMonth?: string
  previousMonth?: string
}

CalendarCustomization

Type Definition:

interface CalendarCustomization {
  classes?: CalendarClasses
  icons?: CalendarIcons
  labels?: CalendarLabels
  translations?: Partial<CalendarTranslations>
}

CalendarListStyle

Type Definition:

type CalendarListStyle = 'grid' | 'list'