Your options in Hapio

EventCalendar takes the options of the calendar you migrate from by their names and passes HapioCalendar the Hapio options on the right. Anything it cannot map is listed once in the console during development. The tables below are @hapio/calendar-compat's own coverage list, which calls the calendar you migrate from "the source library": the package's tests check them against its code both ways, so every option the mapping reads has a row and every row's status is what the mapping does. The types are in the Compat reference; what behaves differently is explained on Differences.

CoverageCopy Anchor Link

Every documented option, callback and method of the source library's Standard API, and its resource options, with what compat does with it. The "Status" column:

Status	Meaning
mapped	Mapped onto a Hapio option with the same behaviour (the notes say how).
differs	Mapped, with a behaviour difference the notes describe.
partly	Some values are mapped; the others (named in the notes) are reported like an unsupported option.
ignored	Accepted without effect and without a report entry.
reported	Not supported: listed in unsupported, with one development warning. The notes say what to use instead.
1.2, 1.3, 1.4	Arrives in that release of Hapio Calendar (the timeline, resource timeline and resource time-grid views); until then reported, with a development error naming the release.

The options tables are checked against the code by the package's tests: every option the mapping reads has a row, and every row's status matches what the mapping does with the option.

Views and navigationCopy Anchor Link

Option	Status	Hapio	Notes
initialView	mapped	defaultView	Seeds the calendar once, as in the source library (re-create it with a React key to reset). An unsupported view id is reported as initialView.<id>.
initialDate	mapped	defaultDate	Read in the calendar's zone; seeds once.
availableViews	mapped	views, in order	The source library's shadcn registry prop. Without it: week, day, month and list, opening on the month (the source library's default view). Unsupported ids are reported as availableViews.<id>.
views	mapped	each view's factory options	Keyed by type (timeGrid), unit (week) or name; the cascade is type, then unit, then name. A used view's options that do not map are reported as views.<key>.<option>; unused views' options are ignored.
duration, dayCount	mapped	a generic view's length	initialView: 'timeGrid', duration: { days: 4 }.
visibleRange, dateIncrement, dateAlignment	reported	—	Hapio views own their length, alignment and step (timeGrid({ days, align, step }) on HapioCalendar).
validRange	partly	validRange	The object form; the function form is reported.
now	partly	now	A fixed date; the function form is reported.
nowIndicator	mapped	nowIndicator
navLinks, navLinkDayClick, navLinkWeekClick	partly	navLinks: { day, week }	View names (default timeGridDay and timeGridWeek, added to the views when supported); the function forms are reported.
navLinkClass	reported	—	Style the registry's day links (calendar-day-grid.tsx, calendar-time-grid.tsx).
datesSet	mapped	onRangeChange	DatesSetInfo: instants, ISO strings with offsets, the zone and the view.
timeZone	mapped	timeZone	Changes take effect without a remount.
locale	partly	locale	A locale code: dates are formatted by Intl. A locale object (the source library's locale modules) is reported: pass its code, and the calendar's texts as strings (sv ships).
locales	reported	—	strings (Hapio's option, which compat takes too; sv ships).
direction	mapped	dir
firstDay	mapped	weekStartsOn	0–6 → ISO weekdays (Sunday 0 → 7).
weekends	mapped	hiddenDays 6 and 7
hiddenDays	mapped	hiddenDays	ISO weekdays. Weekdays as numbers or their strings ('0'); other entries are reported.
fixedWeekCount, showNonCurrentDates	mapped	day grids' fixedWeekCount, showOtherMonthDays	Also per view in views.
weekNumbers	differs	day grids' weekNumbers	Not shown in time grids (a later release); a time grid's views.<key>.weekNumbers is reported.
weekNumberCalculation	partly	—	'ISO' is what Hapio shows (ISO weeks); other values are reported. Without it the source library numbers weeks by the locale, which differs from ISO weeks in the United States.
weekNumberFormat	mapped	formats.weekNumber
weekTextLong, weekTextShort	reported	—	strings on HapioCalendar.

Toolbar, sizing and the shellCopy Anchor Link

Option	Status	Hapio	Notes
headerToolbar, footerToolbar, buttons, buttonDisplay, toolbarElements	reported	—	The block's toolbar, HapioCalendar's toolbar prop, or controller with your own toolbar.
controller	mapped	the block's toolbar	From useCalendarController(): today, prev, next, gotoDate, changeView, getDate, view and getButtonState(). prevYear, nextYear and incrementDate are not provided.
titleFormat	mapped	formats.title
className	mapped	the root's className
height, contentHeight	differs	the root's style.height	Any CSS length, or pixels; 'auto' sets none. Both size the root, which includes the toolbar.
aspectRatio, expandRows, tableHeaderSticky, footerScrollbarSticky, dayMinWidth, dayNarrowWidth	reported	—	Size the root; header rows are sticky; narrow layouts come from the registry's CSS.
borderless, borderlessX, borderlessTop, borderlessBottom	mapped	the view's classes	The registry item's classes (CompatUi.borderlessClasses); reported when the caller gives none.
headingLevel	mapped	headingLevel
colorScheme	reported	—	Dark mode follows the app's theme (the .dark class and the tokens).
todayHint, prevHint, nextHint, viewHint, viewChangeHint, navLinkHint, moreLinkHint, closeHint, eventsHint, moreLinkText, listText	reported	—	strings on HapioCalendar.
plugins	ignored	—	Every view and interaction is built in (selection and editing come from the registry's <CalendarSelection> and <CalendarEditing>).
schedulerLicenseKey	ignored	—	One development notice: every view is free (MIT).

Time axis and daysCopy Anchor Link

Option	Status	Hapio	Notes
slotDuration, snapDuration	mapped	the same
slotMinTime	mapped	slotMin
slotMaxTime	partly	slotMax	Up to '24:00'; later times are reported.
slotHeaderInterval	mapped	slotLabelInterval
slotHeaderFormat	mapped	formats.slotLabel	An array gives tiers, top first.
slotMinHeight, slotHeaderAlign, slotHeaderSticky, eventMinHeight, eventShortHeight	reported	—	The registry's tokens and CSS.
allDaySlot	mapped	allDaySlot
allDayText	mapped	strings.allDay
scrollTime, scrollTimeReset	mapped	scrollTime, resetScrollOnNavigate
businessHours	mapped	businessHours	{ daysOfWeek, startTime, endTime } → { days (ISO), start, end }; true and lists as well. Weekdays as numbers or their strings; other entries are reported.
dayHeaders	reported	—
dayHeaderFormat	mapped	formats.dayHeader
dayCellFormat, monthStartFormat	reported	—
listDayFormat, listDayAltFormat	mapped	formats.listDay, formats.listDayAlt	The list's day headings; false leaves the text empty.

Events and sourcesCopy Anchor Link

Option	Status	Hapio	Notes
events	partly	events, backgroundEvents, series, eventSources	An array (see "Event fields"), or a function (an event source whose info adds signal; success/failure or a returned value or promise). A feed URL is reported.
eventSources	partly	events or eventSources	Arrays and functions, with each source's color, className and editing fields; feed sources (url, format, googleCalendarId, …) are reported as eventSources.<key>.
initialEvents	reported	—	Pass events (compat keeps kept changes over them, see "Behaviour").
eventSourceSuccess, eventSourceFailure, eventDataTransform, startParam, endParam, timeZoneParam, lazyFetching, progressiveEventRendering, rerenderDelay	reported	—	Fetch in an events function (or TanStack Query) and pass the result.
loading	mapped	onLoadingChange
defaultTimedEventDuration, defaultAllDayEventDuration	mapped	defaultTimedDuration, defaultAllDayDuration
defaultAllDay, forceEventDuration	reported	—	All-day is read from each event's allDay or the form of its start.
nextDayThreshold	mapped	nextDayThreshold
eventColor, eventContrastColor, backgroundEventColor	reported	—	Each event's or source's color; the default colors are the registry's tokens.
eventDisplay, displayEventTime, displayEventEnd, eventSlicing, eventInteractive	reported	—	eventContent for the content; every event is focusable.
eventTimeFormat	mapped	formats.eventTime
eventOrder, eventOrderStrict	mapped	eventOrder, orderStrict	String keys ('start,-duration,allDay,title', extended props included), arrays and functions of EventApi.
dayMaxEvents, dayMaxEventRows	differs	maxEvents per view kind	Day grids: true → 'auto', a number N of events → N + 1 levels (Hapio counts the "+N more" row), rows as given. A time grid's all-day row: 5 rows under true, as the source library. At exactly N + 1 events a day shows them all, where the source library shows N and "+1 more".
eventMaxStack	differs	maxStack	N → N + 1 (Hapio counts the "+N" column); at exactly N + 1 overlapping events all show.
moreLinkClick	partly	—	'popover' (Hapio's "+N more" popover); other values are reported.
popoverFormat	mapped	formats.moreTitle	Default "Thu 22", as the source library's shadcn shell.
slotEventOverlap	mapped	overlap: 'stack' | 'columns'
eventClick	mapped	onEventClick	jsEvent.preventDefault() cancels the link navigation; modified clicks reach the browser; a middle click does not call it.
eventMouseEnter, eventMouseLeave	reported	—	eventContent's own handlers.
eventsSet, eventAdd, eventRemove	reported	—	The app owns its events: they change when it changes them.
eventChange	differs	onEventChange	Called after eventDrop or eventResize, for moves and resizes only (there are no mutation methods to call it for).

RenderingCopy Anchor Link

Option	Status	Hapio	Notes
eventContent	mapped	renderEvent	EventDisplayInfo; returning true or nothing renders the default content. { html } and { domNodes } render the default content (given directly instead of a function, they are reported).
backgroundEventContent	mapped	renderBackgroundEvent	The content names the background event (its role="img").
eventClass, backgroundEventClass, viewClass, dayHeaderClass, dayCellClass, dayLaneClass, moreLinkClass, nowIndicatorLineClass, listDayClass, noEventsClass	mapped	classNames.<part>	A string, a list or a function of the part's info.
noEventsText	mapped	strings.noEvents
strings	mapped	strings	Hapio's option, not the source library's: the calendar's texts, accessible names and announcements (sv from @hapio/calendar-core/locales/sv, or members of your own). noEventsText and allDayText win over the members they map to.
dayHeaderContent, dayCellTopContent, slotHeaderContent, allDayHeaderContent, weekNumberHeaderContent, inlineWeekNumberContent, nowIndicatorHeaderContent, nowIndicatorLineContent, moreLinkContent, popoverCloseContent, listDayHeaderContent, noEventsContent, rowEventBeforeContent, rowEventAfterContent	reported	—	HapioCalendar's renderDayHeader and renderEmpty, or the registry's files (they are yours to edit).
eventInnerClass, eventTimeClass, eventTitleClass, blockEventClass, rowEventClass, columnEventClass, listItemEventClass, dayRowClass, dayCellInnerClass, slotLaneClass, slotHeaderClass, allDayHeaderClass, nowIndicatorHeaderClass, nowIndicatorDotClass, popoverClass, toolbarClass, buttonClass, tableClass, highlightClass, nonBusinessHoursClass, listDayHeaderClass, and every other *Class hook	reported	—	The registry's files and classNames on HapioCalendar (timeClass/titleClass in eventContent style the default content's parts).
eventDidMount, eventWillUnmount, viewDidMount, dayCellDidMount, and every other *DidMount/*WillUnmount hook	reported	—	Refs and effects in eventContent.

Selection, editing and dropsCopy Anchor Link

The interactions need their engine, which the registry's <CalendarSelection> or <CalendarEditing> (and <CalendarExternalDrops>) gives the compat component, as the source library's interaction plugin did; compat never imports it.

Option	Status	Hapio	Notes
selectable	mapped	selectable
selectMirror	mapped	selectionPreview	true → 'event', false → 'highlight'.
unselectAuto	mapped	clearSelectionOnOutsidePointer
unselectCancel, selectMinDistance	reported	—	A press outside always clears (unselectAuto: false keeps selections); drags start past 5 px.
selectConstraint, selectOverlap, selectAllow	differs	rules.select	A group id becomes { group }. Background events never block a selection.
dateClick	mapped	onDateClick	Also Enter (and Space where it does not select) on a day cell or the slot cursor; jsEvent is then the keydown (typed MouseEvent | KeyboardEvent).
select, unselect	mapped	onSelect, onSelectionChange(null)	jsEvent is null for a keyboard selection; a replaced selection is unselected first, as in the source library.
editable, eventStartEditable, eventDurationEditable, eventResizableFromStart	mapped	editable flags	With each event's and source's fields over them, field by field.
eventConstraint, eventOverlap, eventAllow	differs	rules.event	A group id becomes { group }. Background events never count as overlaps. An object constraint's weekdays as numbers or their strings; other entries are reported.
eventDrop, eventResize	differs	onEventChange	revert() makes the result false; jsEvent is the DOM event that ended the change (a KeyboardEvent for the keyboard); no el. Kept changes are held (see "Behaviour").
eventDragStart, eventDragStop, eventResizeStart, eventResizeStop, eventLeave	reported	—	No such callbacks; dragging out of a calendar is a later release.
eventDragMinDistance, dragRevertDuration, fixedMirrorParent	reported	—	Drags start past 5 px; a revert animates for 200 ms.
dragScroll	partly	—	true is Hapio's behaviour; false is reported.
allDayMaintainDuration	partly	—	false is Hapio's behaviour (a move between the all-day row and the lanes takes the default duration); true is reported.
longPressDelay, eventLongPressDelay, selectLongPressDelay	differs	longPressMs	One delay: the most specific option given wins.
droppable, dropAccept	mapped	droppable, acceptExternal	droppable alone accepts every item; a selector matches the draggable element.
drop, eventReceive	differs	onExternalDrop	draggedEl is the draggable element (else the drop's data); jsEvent the release, click or key that placed it; eventReceive only for object data, which compat reads as an EventInput.

RecurrenceCopy Anchor Link

Option	Status	Hapio	Notes
recurrence, recurrenceScope	mapped	recurrence, recurrenceScope	Hapio's options (the source library needs a plugin instead): with recurrence: rrule() the simple recurrence fields and rrule become series; 'all' is the default scope, as the source library moves every instance.

Resources and timelinesCopy Anchor Link

Option	Status	Hapio	Notes
resources, resourceOrder, resourceColumnHeaderContent, resourceColumnsWidth, resourceColumns, resourceGroupField, eventResourceEditable	1.3	—	Typed, so apps keep compiling. Every option whose name contains resource is treated so.

View idsCopy Anchor Link

View id	Status	Hapio	Notes
timeGridWeek, timeGridDay	mapped	timeGrid({ days: 7 | 1 })	Labelled "Week" and "Day" (radios "Week view", "Day view").
timeGrid	mapped	timeGrid({ days })	With a duration or dayCount (1–31 days), in views or at the top level.
dayGridMonth, dayGridWeek, dayGridDay	mapped	dayGrid({ unit })	"Month".
dayGrid	partly	dayGrid({ unit })	A duration of one day, week or month; others are reported.
listDay, listWeek, listMonth	mapped	list({ unit })	"List".
listYear, dayGridYear, multiMonthYear, multiMonth	reported	—
timelineDay, timelineWeek, timelineMonth, timelineYear	1.2	—
resourceTimelineDay, resourceTimelineWeek, resourceTimelineMonth	1.3	—
resourceTimeGridDay, resourceTimeGridWeek	1.4	—
resourceDayGridDay, resourceDayGridWeek, resourceDayGridMonth	reported	—	Not planned.

Custom views (views: { fourDay: { type: 'timeGrid', duration: { days: 4 } } }) are supported for these kinds, and their buttonText is the label.

Event fields (EventInput)Copy Anchor Link

Field	Status	Notes
id, groupId, title, start, end, date, allDay, display, editable, startEditable, durationEditable, constraint, overlap, allow	mapped	An event without id gets one from its position and start (a development warning asks for ids). display: 'background' and 'inverse-background' make background events.
url	mapped	href: a real link.
color, contrastColor, backgroundColor, textColor	mapped	Any CSS color, as --event-color/--event-contrast and the --fc-event-color/--fc-event-contrast-color aliases (legacyEventVars).
className, class	mapped	On the event's root element (a string or a list).
extendedProps, and any other field	mapped	data.
interactive	ignored	Every event is focusable.
resourceId, resourceIds, resourceEditable	mapped	Passed on to the calendar; the resource views that use them arrive in 1.3.
daysOfWeek, startTime, endTime, startRecur, endRecur, rrule, exdate, duration	partly	With recurrence: a series. Without it: reported as events.<field> (the event shows once if it has a start). Recurring background events and events from a function are not expanded. daysOfWeek takes weekdays as numbers or their strings ('4'); other entries are reported (events.daysOfWeek).
exrule	reported	RFC 5545 deprecates it.
rdate, overrides	mapped	Hapio's additions for series (extra dates; changed instances).

Payloads, facades and methodsCopy Anchor Link

Source library	Status	Notes
EventApi	differs	Read-only: id, groupId, title, start, end, startStr, endStr, allDay, url, display, extendedProps, and the colors and classes as backgroundColor, textColor, classNames. No source, editable flags, constraint, overlap, and no methods (setProp, remove, toPlainObject, …): change your events and pass them again.
ViewApi	differs	type, title, activeStart, activeEnd, currentStart, currentEnd; no calendar or getOption.
DatesSetInfo, EventClickInfo	mapped
DateClickInfo, DateSelectInfo, DropInfo	differs	No resource until 1.3.
EventDropInfo, EventResizeDoneInfo, EventChangeInfo	differs	No el; jsEvent may be a KeyboardEvent or null; an instance of a recurring event has relatedEvents: [] and Hapio's recurrence.
EventDisplayInfo	differs	isNarrow is always false; isFuture is !isPast && !isToday; no isFirst, isLast, isResizing, isDraggable, isStartResizable, isEndResizable, isInteractive or level.
DayCellInfo (day cells, headers, lanes, list days)	differs	date, dateStr, dow, isOther, isToday, isPast, isFuture, isDisabled, view; no text parts.
getApi() and the calendar's methods	reported	There is no imperative API: a ref is reported. Navigate with controller, change data by passing new events, select with HapioCalendar's selection.
Draggable, ThirdPartyDraggable	reported	Not provided: useExternalDraggable (@hapio/calendar-react/interaction) or the registry's CalendarDraggable, whose data is what eventReceive reads; other drag-and-drop libraries reach the calendar through its store's hitTest.
Format strings (Moment, Luxon plugins)	reported	Intl.DateTimeFormat options or a function; omitCommas, forceCommas, omitZeroMinute and meridiem are supported, omitTrailing and weekdayJustify are reported (eventTimeFormat.omitTrailing).
Older option names (slotLabelFormat, eventClassNames, dayCellContent, …)	reported	Use the current names.

BehaviourCopy Anchor Link

• Kept changes stay. The source library keeps a dropped or resized event where it was left, in its own store. With useCompatProps (the event-calendar item), compat does the same: a change the callbacks keep is held over the app's events (and eventSources arrays) until the app's input for that event changes its start, end or allDay (saving the change, or any other value: the app's data wins) or leaves the input. A reverted change is not held. Changes to an instance of a recurring event, and to events an events function returned, are not held: save them (the plan in info.recurrence, or a refetch), or they return after the settle timeout (15 s). fromCompatOptions alone holds nothing.
• Overlap ignores background events. In the source library a background event counts as an overlap; in Hapio it never does. Use constraint: '<groupId>' (a background event's group) to keep events inside, for example, open hours.
• Day limits count events (the source library) or levels including the "+N more" row (Hapio): compat converts, and at exactly N + 1 events Hapio shows them all.
• Week numbers show in day grids only; time grids show none yet.
• isFuture is !isPast && !isToday.
• jsEvent of a change or a drop is the DOM event that ended it: a pointer release, a click, or the key (Enter) that dropped a keyboard grab, typed MouseEvent | KeyboardEvent | null. There is no el for changes and drops.

TypingCopy Anchor Link

EventCalendarProps declares every option the tables above map (mapped, differs, partly and ignored), so a typed options object keeps compiling (satisfies EventCalendarProps). The options marked reported, and those of 1.2–1.4 except the six below, are not declared: in a typed app passing one is a type error (TS2353, "Object literal may only specify known properties"), and step 4 of the migration ("Replace what has no counterpart") removes them. Options that reach compat untyped (from JavaScript, or spread from an object of the app's own type) are reported in unsupported, with a development warning. The resource options of 1.3 that apps commonly pass (resources, resourceOrder, resourceColumnHeaderContent, resourceColumnsWidth, resourceColumns, resourceGroupField) are declared, so they compile and are reported with the release that brings them.