API Reference

All date-picking components require an adapter. Their public values use native JavaScript Date objects; calendar-specific parts are only exposed to adapter and headless-hook APIs.

Shared calendar options

Calendar, DatePicker, useCalendar, and useDatePicker accept these options.

Prop	Type	Default
`adapter`	`CalendarAdapter`	required
`mode`	`"single" \| "multiple" \| "range" \| "week" \| "month" \| "quarter" \| "year"`	`"single"`
`value` / `defaultValue`	`CalixValue`	mode empty value
`onChange`	`(value: CalixValue) => void`	—
`onSelect`	`(value: CalixValue, complete: boolean) => void`	—
`locale`	`string`	adapter default
`dir`	`"ltr" \| "rtl"`	adapter locale result
`labels`	`PickerLabels`	localized defaults
`theme`	`"dark" \| "light"`	`"dark"`
`weekStartsOn`	`0`–`6`	Saturday for `fa-*`, Sunday otherwise
`defaultMonth`	`Date`	selected date or today
`numberOfMonths`	`number`	`1`
`fixedWeeks`	`boolean`	`true`
`max`	`number`	—; multiple mode only
`minRange` / `maxRange`	`number`	—; inclusive days, range mode only
`weekendDays`	`Weekday[]`	`[5]` for `fa-*`, `[0, 6]` otherwise
`onMonthChange`	`(view: MonthView) => void`	—; excludes initial render
`onFocusChange`	`(date: CalendarDate) => void`	—; excludes initial render
`onOutputChange`	`(value: string) => void`	—
`outputFormat`	`"string" \| "json"`	`"string"`
`outputPattern`	`string`	`"yyyy-MM-dd"`

complete is false only while a range is waiting for its end date.

Constraints

Prop	Type	Meaning
`minDate` / `maxDate`	`Date`	Inclusive allowed boundaries.
`disabledDates`	`Date[]`	Explicitly blocked dates.
`enabledDates`	`Date[]`	When present, only these dates are allowed.
`disabledWeekdays`	`Weekday[]`	`0` Sunday through `6` Saturday.
`disabledMonths` / `disabledYears`	`number[]`	Calendar month numbers (1-based) or years to block.
`businessDaysOnly`	`boolean`	Blocks the configured `weekendDays`.
`weekendDays`	`Weekday[]`	Weekend days; `[5]` for `fa-*`, `[0, 6]` otherwise.
`holidays`	`Date[]`	Dates treated as blocked.
`holidayData`	`readonly Holiday[]`	Named dates for holiday markers and tooltips.
`showHolidays`	`boolean`	Shows holiday markers and names; default `false`.
`holidaysSelectable`	`boolean`	Keeps `holidayData` dates selectable; default `true`.
`isDateDisabled`	`(date, adapter) => boolean`	Return `true` to block a calendar date.

`<DatePicker>`

The convenience popover picker. In addition to shared options:

Prop	Type	Default
`placeholder`	`string`	`"Select date"`
`pattern`	`string`	`"yyyy/MM/dd"` or date-time equivalent
`classNames`	`DatePickerClassNames`	—
`withTime`	`boolean`	`false`
`timePickerProps`	`TimeFieldProps` without value handlers	—
`showToday` / `showClear` / `showCancel`	`boolean`	`true` / `false` / `true`
`infiniteScroll`	`boolean`	`false`
`presets`	`CalendarPreset[]`	—
`open` / `defaultOpen`	`boolean`	uncontrolled / `false`
`onOpenChange`	`(open: boolean) => void`	—
`closeOnSelect`	`boolean`	`true`
`placement`	Popover placement	`"bottom-start"`
`offset`	`number`	`8`

DatePicker.Root takes the shared options plus open-state options. DatePicker.Trigger is a button wired to the popover. DatePicker.Input accepts all native input props plus pattern, mask, and reference. DatePicker.Content accepts classNames, className (the popover surface), showToday, showCancel, portal (default true), and custom children.

`<Calendar>` and `<CalendarView>`

Calendar is an inline component that takes shared options plus:

Prop	Type
`classNames`	`CalendarClassNames`
`renderDay`	`(date: CalendarDate, defaultLabel: string) => ReactNode`
`header` / `footer`	`ReactNode \| (calendar) => ReactNode`
`showToday` / `showClear` / `infiniteScroll`	`boolean`

CalendarView is presentational. It receives a calendar result returned by useCalendar, then accepts the same rendering props above.

CalendarClassNames has slots: root, header, heading, nav, navButton, months, grid, weekdays, weekday, week, day, footer, footerButton, presets, preset, picker, pickerBody, month, and year. DatePickerClassNames includes every CalendarClassNames slot plus popover, field, input, toggle, clear, dateTime, timeStep, timeBack, timeTitle, and timeActions.

`<TimeField>`, `<MonthPicker>`, and `<YearPicker>`

TimeField takes value, defaultValue, onChange, hourCycle (12 or 24), minuteStep, secondStep, withSeconds, variant ("field", "wheel", or "analog"), labels, theme, className, and disabled.

MonthPicker forces month selection; YearPicker forces year selection. Both take shared calendar options. YearPicker also has pageSize (default 12).

Hooks

Hook	Returns
`useCalendar(options)`	Calendar state, navigation, selection methods, checks, grids, and prop getters.
`useDatePicker(options)`	`useCalendar` plus popover state, refs/styles, and interaction getters.
`useDateInput(options)`	`inputValue`, `setInputValue`, and `getInputProps`.
`useTime(options?)`	Time value, display state, setters, and increment helpers.
`useControllableState(options)`	Controlled/uncontrolled state primitive.

Values and types

CalixValue is Date | Date[] | RangeValue | null; RangeValue is { start: Date | null; end: Date | null }. Weekday is 0 through 6.

PickerLabels can override weekdays, navigation, month/year choices, time labels, and today/now/confirm/clear/cancel actions. See Localization.

`CalendarAdapter`

Every calendar adapter implements: today; toDate / fromDate; day, month, and year arithmetic; month boundaries; month length and leap-year rules; weekday, month-grid, year-range, and week-number methods; comparison/equality; parsing, formatting, localized names, and RTL detection.

Import it from @alydev/core:

import type { CalendarAdapter, CalendarDate, Time } from "@alydev/core";

Core exports

@alydev/core also exports generateMonthGrid, buildDisabledPredicate, nearestEnabledDate, selection-strategy helpers, date comparison and range helpers, localized digit helpers, formatTokens, parseTokens, and the core calendar/date/selection types.