API Reference
For full TypeScript definitions and detailed signatures, see the generated API documentation.
Properties
| data: CalendarData | All calendars and items (read-only). |
| settings: EventCalendarSettings | Settings object — access theme, locale, firstDayOfWeek, workingHours, slotDuration (read-only). |
| events: EventCalendarEvents | Event emitters (read-only). |
| viewMode: ViewMode | Current view mode ('month' | 'week' | 'day' | 'agenda'). |
| currentDate: Date | The date the calendar is centered on. |
| canEdit: boolean | Enable/disable editing. Default: true. |
| sidebarVisible: boolean | Show/hide the sidebar (mini calendar + calendar list). Default: true. |
| selectedEntries: CalendarEntry[] | Currently selected entries. |
| selectedEntry: CalendarEntry | null | Last selected entry (or null). |
| entryRendering: EntryRenderFn | null | Custom entry rendering function. |
| entryTooltip: EntryTooltipFn | null | Custom tooltip content function. |
| canUndo$: BehaviorSubject<boolean> | Whether undo is available (observable, read-only). |
| canRedo$: BehaviorSubject<boolean> | Whether redo is available (observable, read-only). |
Methods
| load(json: string): void | Load data from a JSON string. |
| save(): string | Serialize current state to a JSON string. |
| today(): void | Navigate to today's date. |
| next(): void | Navigate to the next period (day/week/month). |
| previous(): void | Navigate to the previous period. |
| goToDate(date: Date): void | Navigate to a specific date. |
| undo(): void | Undo the last action. |
| redo(): void | Redo the last undone action. |
| copyEntries(entries?: CalendarEntry[]): Promise<void> | Copy entries to clipboard (defaults to selected). |
| cutEntries(entries?: CalendarEntry[]): Promise<void> | Cut entries to clipboard. |
| pasteEntries(): Promise<void> | Paste entries from clipboard. |
| exportToImage(options?: CalendarImageExportOptions): Promise<Blob> | Export current view as PNG image. Requires html2canvas. |
| exportToPdf(options?: CalendarPdfExportOptions): Promise<Blob> | Export as PDF document. Requires jspdf. |
| exportToIcs(options?: CalendarIcsExportOptions): Blob | Export as iCalendar (.ics) file (RFC 5545). |
| exportToIcsText(options?: CalendarIcsExportOptions): string | Export as iCalendar text string. |
| exportToCsv(options?: CalendarCsvExportOptions): string | Export as CSV string. |
| exportToExcel(options?: CalendarExcelExportOptions): Promise<Blob> | Export as Excel (.xlsx). Requires exceljs. |
| importFromIcs(text: string, options?: CalendarIcsImportOptions): CalendarIcsImportResult | Import from iCalendar text. |
| destroy(): void | Destroy the calendar and release all DOM resources. |
Events
All events are RxJS Subject instances. Subscribe via calendar.events.eventName$.subscribe(callback).
Calendar Data Events
| calendarAdded$: Subject<CalendarEventArgs> | A calendar was added. |
| calendarChanged$: Subject<CalendarEventArgs> | A calendar property changed. |
| calendarRemoved$: Subject<CalendarEventArgs> | A calendar was removed. |
| calendarAddRequested$: Subject<void> | The 'Add calendar' button was clicked in the sidebar. |
| calendarRemoving$: Subject<CalendarRemovingArgs> | A calendar is about to be removed (cancelable). |
| itemAdded$: Subject<CalendarItemEventArgs> | An item was added. |
| itemChanged$: Subject<CalendarItemEventArgs> | An item property changed. |
| itemRemoved$: Subject<CalendarItemEventArgs> | An item was removed. |
Entry Interaction Events
| entryClick$: Subject<EntryEventArgs> | An entry was clicked. |
| entryDblClick$: Subject<EntryEventArgs> | An entry was double-clicked. |
| entryContextMenu$: Subject<EntryContextMenuArgs> | An entry was right-clicked. |
| dateClick$: Subject<DateClickArgs> | An empty date/time was clicked. |
| dateContextMenu$: Subject<DateContextMenuArgs> | An empty date/time was right-clicked. |
| moreClick$: Subject<MoreClickArgs> | The '+N more' overflow was clicked in month view. |
Drag & Resize Events (Cancelable)
| entryMoving$: Subject<EntryMovingArgs> | An entry is being moved. Set cancel = true to prevent. |
| entryResizing$: Subject<EntryResizingArgs> | An entry is being resized. Set cancel = true to prevent. |
| entryCreating$: Subject<EntryCreatingArgs> | A new entry is being created via drag. Set cancel = true to prevent. |
| entryDeleting$: Subject<EntryDeletingArgs> | An entry is about to be deleted. Set cancel = true to prevent. |
Navigation & Selection Events
| viewModeChanged$: Subject<ViewMode> | The view mode changed. |
| currentDateChanged$: Subject<Date> | The current date changed. |
| viewDateRangeChanged$: Subject<{ start: Date, end: Date }> | The visible date range changed. |
| selectedEntriesChanged$: Subject<CalendarEntry[]> | Entry selection changed. |
| selectedEntryChanged$: Subject<CalendarEntry | null> | Last selected entry changed (or null). |
| undone$: Subject<void> | An undo was performed. |
| redone$: Subject<void> | A redo was performed. |
Types & Enums
Calendar
| id: string | Unique identifier (auto-generated if not provided). |
| name: string | Display name. Default: ''. |
| color: ColorValue | Color index or custom ColorDefinition. Default: 0. |
| isVisible: boolean | Whether items from this calendar are shown. Default: true. |
| isDefault: boolean | Whether this is the default calendar for new items. Default: false. |
| isReadOnly: boolean | Whether items in this calendar can be edited. Default: false. |
| timeZone: string | null | IANA time zone identifier. Default: null. |
| description: string | null | Calendar description. Default: null. |
CalendarItem (base class)
| id: string | Unique identifier (read-only, auto-generated if not provided). |
| type: CalendarItemType | Discriminator for the concrete item type (read-only). |
| calendarId: string | null | ID of the calendar this item belongs to. Default: null. |
| startTime: Date | null | Start date/time. Default: null. |
| endTime: Date | null | End date/time (must be >= startTime). Default: null. |
| timeZone: string | null | IANA time zone identifier. Default: null. |
| isAllDay: boolean | Whether this is an all-day event. Default: false. |
| title: string | null | Display title. Default: null. |
| description: string | null | Description or notes. Default: null. |
| location: string | null | Location text. Default: null. |
| color: ColorValue | Color index or custom ColorDefinition. Default: 0 (inherits from calendar). |
| visibility: CalendarItemVisibility | Visibility level. Default: 'public'. |
| recurrenceRule: RecurrenceRule | null | Recurrence rule for repeating events. Default: null. |
| recurrenceExceptions: readonly RecurrenceException[] | Occurrence overrides/cancellations (read-only array). |
| isRecurring: boolean | Whether item has a recurrence rule (computed, read-only). |
| hasReminders: boolean | Whether reminders are set. Default: false. |
| externalSource: ExternalSource | string | null | Source system identifier. Default: null. |
| tags: string[] | null | Tags/categories. Default: null. |
| data: any | Arbitrary user data. Default: undefined. |
CalendarItem Methods
| setException(exception: RecurrenceException): void | Add or update a recurrence exception. |
| removeException(originalStartTime: Date): void | Remove a recurrence exception. |
| cancelOccurrence(originalStartTime: Date): void | Cancel a single occurrence (EXDATE). |
| getException(originalStartTime: Date): RecurrenceException | null | Get exception for a specific occurrence. |
| clearExceptions(): void | Remove all recurrence exceptions. |
| clone(newId: string | null): CalendarItem | Create a deep copy with a new ID. |
| addProperty(property: CustomProperty): void | Add a custom property. |
| removeProperty(property: CustomProperty): void | Remove a custom property. |
| getPropertyByName(name: string): CustomProperty | null | Get a custom property by name. |
| getPropertyValue(name: string): any | Get a custom property value. |
| setPropertyValue(name: string, value: any): void | Set a custom property value. |
CalendarItemType
| 'meeting' | Meeting with attendees, RSVP, and organizer. Class: Meeting. |
| 'appointment' | Personal time block without attendees. Class: Appointment. |
| 'task' | Task with deadline and completion state. Class: Task. |
| 'deadline' | Milestone without duration. Class: Deadline. |
| 'availabilityBlock' | Focus/OOF/busy/tentative block. Class: AvailabilityBlock. |
| 'holiday' | Public/company holiday (typically read-only). Class: Holiday. |
| 'birthday' | Birthday (typically from contacts). Class: Birthday. |
| 'reminder' | Standalone reminder without duration. Class: Reminder. |
| 'resourceBooking' | Shared resource booking (room, vehicle). Class: ResourceBooking. |
Meeting (extends CalendarItem)
| responseStatus: ResponseStatus | User's RSVP status. Default: 'needsAction'. |
| attendeeCount: number | Number of attendees. Default: 0. |
| hasConference: boolean | Whether a video conference link is attached. Default: false. |
| organizer: string | null | Organizer name or email. Default: null. |
Task (extends CalendarItem)
| isCompleted: boolean | Whether the task is completed. Default: false. |
| completedAt: Date | null | Completion timestamp. Default: null. |
| priority: number | Priority level (0 = none, 1 = highest). Default: 0. |
AvailabilityBlock (extends CalendarItem)
| availabilityStatus: AvailabilityStatus | Availability type. Default: 'busy'. |
Birthday (extends CalendarItem)
| contactName: string | null | Contact name. Default: null. |
ResourceBooking (extends CalendarItem)
| resourceId: string | null | Booked resource ID. Default: null. |
| resourceName: string | null | Booked resource display name. Default: null. |
CalendarEntry
| item: CalendarItem | The master CalendarItem (read-only). |
| originalStartTime: Date | Start time of this occurrence per the recurrence rule (read-only). |
| exception: RecurrenceException | null | Applied exception, if any (read-only). |
| id: string | Unique entry ID (itemId for non-recurring, itemId_isoDate for recurring; computed). |
| type: CalendarItemType | Item type (computed from item). |
| calendarId: string | null | Calendar ID (computed from item). |
| startTime: Date | Effective start time (exception override > original; computed). |
| endTime: Date | Effective end time (exception override > computed from duration; computed). |
| title: string | null | Effective title (exception override > item; computed). |
| description: string | null | Effective description (computed). |
| location: string | null | Effective location (computed). |
| color: ColorValue | Effective color (computed). |
| isAllDay: boolean | Effective all-day flag (computed). |
| timeZone: string | null | Effective time zone (computed). |
| tags: string[] | null | Effective tags (computed). |
| isRecurring: boolean | Whether the master item is recurring (computed). |
| isException: boolean | Whether this entry has a non-cancelled exception (computed). |
| isCancelled: boolean | Whether this occurrence is cancelled (computed). |
| responseStatus: ResponseStatus | Effective RSVP status (Meeting only; computed). |
| isCompleted: boolean | Effective completion state (Task only; computed). |
CalendarData — Calendar Methods
| calendarsLength: number | Number of calendars (read-only). |
| getCalendar(index: number): Calendar | Get calendar by index. |
| getCalendarById(id: string): Calendar | null | Find calendar by ID. |
| addCalendar(calendar: Calendar): void | Add a calendar. |
| removeCalendar(calendar: Calendar): void | Remove a calendar (cannot remove default). |
| assignCalendars(calendars: Calendar[]): void | Replace all calendars (at least one must be default). |
| defaultCalendar: Calendar | null | The default calendar (read-only, computed). |
CalendarData — Item Methods
| itemsLength: number | Number of items (read-only). |
| getItem(index: number): CalendarItem | Get item by index. |
| getItemById(id: string): CalendarItem | null | Find item by ID. |
| getItemsForCalendar(calendarId: string): CalendarItem[] | Get all items for a calendar. |
| addItem(item: CalendarItem): void | Add an item. |
| removeItem(item: CalendarItem): void | Remove an item. |
| assignItems(items: CalendarItem[]): void | Replace all items. |
| clear(): void | Remove all calendars and items. |
CalendarData — Entry & Color Methods
| getEntries(range: TimeRange): CalendarEntry[] | Get expanded entries for visible range (handles recurrence). |
| getItemColor(item: CalendarItem): ColorValue | Resolve item color (falls back to calendar color). |
| getEntryColor(entry: CalendarEntry): ColorValue | Resolve entry color (falls back to calendar color). |
RecurrenceRule
| frequency: RecurrenceFrequency | Recurrence frequency (required). |
| interval: number | Interval between occurrences. Default: 1. |
| until: Date | null | End date (mutually exclusive with count). Default: null. |
| count: number | null | Max number of occurrences (mutually exclusive with until). Default: null. |
| byDay: readonly WeekdayOrdinal[] | Days of the week (e.g. MO, 2TU for second Tuesday). Default: []. |
| byMonthDay: readonly number[] | Days of the month (1-31, negative from end). Default: []. |
| byMonth: readonly number[] | Months (1-12). Default: []. |
| bySetPos: readonly number[] | Position within the frequency period. Default: []. |
| weekStart: Weekday | First day of the week. Default: 'mo'. |
RecurrenceRule Methods
| constructor(init: RecurrenceRuleInit) | Create a new rule from an init object. |
| static fromString(rrule: string): RecurrenceRule | Parse from iCalendar RRULE string. |
| toString(): string | Serialize to iCalendar RRULE string. |
| expandBetween(dtStart, rangeStart, rangeEnd): Date[] | Generate occurrence dates within a time range. |
| static fromAny(data: any): RecurrenceRule | Deserialize from JSON. |
| toAny(): any | Serialize to JSON. |
RecurrenceException
| originalStartTime: Date | Original occurrence start time (slot identifier). |
| isCancelled: boolean | Whether this occurrence is cancelled (EXDATE). |
| overrides: CalendarItemOverrides | null | Overridden properties (only set keys override the master). |
CalendarItemOverrides
| startTime?: Date | Override start time. |
| endTime?: Date | Override end time. |
| title?: string | null | Override title. |
| description?: string | null | Override description. |
| location?: string | null | Override location. |
| color?: ColorValue | Override color. |
| isAllDay?: boolean | Override all-day flag. |
| timeZone?: string | null | Override time zone. |
| tags?: string[] | null | Override tags. |
| responseStatus?: ResponseStatus | Override RSVP status (Meeting). |
| isCompleted?: boolean | Override completion state (Task). |
| completedAt?: Date | null | Override completion timestamp (Task). |
EventCalendarSettings
| locale: TimelineKitLocale | Locale for formatting and translations. |
| theme: EventCalendarTheme | Visual theme. |
| firstDayOfWeek: number | First day of the week (0 = Sunday, 1 = Monday, ...). Default: 1. |
| showWeekNumbers: boolean | Show week numbers in month view and mini calendar. Default: false. |
| slotDuration: number | Time slot duration in minutes (must divide 60: 5, 10, 15, 20, 30, 60). Default: 30. |
| workingHours: { start: number, end: number } | Working hours range (0-24). Default: { start: 8, end: 17 }. |
| agendaDays: number | Number of days shown in agenda view (1-90). Default: 14. |
EntryEventArgs
| entry: CalendarEntry | The clicked/interacted entry. |
| domEvent: MouseEvent | The original DOM mouse event. |
EntryContextMenuArgs
| entry: CalendarEntry | The right-clicked entry. |
| domEvent: MouseEvent | The original DOM mouse event. |
DateClickArgs
| date: Date | The clicked date/time. |
| isAllDay: boolean | Whether the click was in the all-day section. |
| domEvent: MouseEvent | The original DOM mouse event. |
DateContextMenuArgs
| date: Date | The right-clicked date/time. |
| isAllDay: boolean | Whether the click was in the all-day section. |
| entry: CalendarEntry | null | Entry under the cursor, if any. |
| domEvent: MouseEvent | The original DOM mouse event. |
MoreClickArgs
| date: Date | The date of the '+N more' label. |
| entries: CalendarEntry[] | All entries for that date. |
EntryMovingArgs (cancelable)
| entry: CalendarEntry | The entry being moved. |
| newStartTime: Date | Proposed new start time. |
| newEndTime: Date | Proposed new end time. |
| cancel: boolean | Set to true to prevent the move. |
EntryResizingArgs (cancelable)
| entry: CalendarEntry | The entry being resized. |
| newStartTime: Date | Proposed new start time. |
| newEndTime: Date | Proposed new end time. |
| edge: 'start' | 'end' | Which edge is being resized. |
| cancel: boolean | Set to true to prevent the resize. |
EntryCreatingArgs (cancelable)
| startTime: Date | Start time of the new entry. |
| endTime: Date | End time of the new entry. |
| isAllDay: boolean | Whether the entry is in the all-day section. |
| cancel: boolean | Set to true to prevent creation. |
EntryDeletingArgs (cancelable)
| entry: CalendarEntry | The entry being deleted. |
| isRecurring: boolean | Whether the entry belongs to a recurring series. |
| scope: 'this' | 'thisAndFollowing' | 'all' | Deletion scope for recurring entries. Changeable by subscriber. |
| cancel: boolean | Set to true to prevent deletion. |
CalendarRemovingArgs (cancelable)
| calendar: Calendar | The calendar being removed. |
| cancel: boolean | Set to true to prevent removal. |
CalendarEventArgs
| calendar: Calendar | The affected calendar. |
CalendarItemEventArgs
| item: CalendarItem | The affected item. |
EntryRenderArgs
| entry: CalendarEntry | The entry being rendered. |
| element: HTMLElement | The DOM element — modify content/style to customize. |
| isAllDay: boolean | Whether the entry is in the all-day section. |
| viewMode: ViewMode | Current view mode. |
| color: EventCalendarEntryColor | Resolved color palette for this entry. |
EntryRenderFn
| (args: EntryRenderArgs) => boolean | void | Return true if you handled the rendering (default content is cleared). Return false/undefined to keep default rendering. |
EntryTooltipArgs
| entry: CalendarEntry | The hovered entry. |
| viewMode: ViewMode | Current view mode. |
EntryTooltipContent
| title: string | Tooltip title text. |
| rows?: { label: string, value: string }[] | Key-value rows displayed below the title. |
EntryTooltipFn
| (args: EntryTooltipArgs) => EntryTooltipContent | null | Promise<...> | Return content to display, or null to hide tooltip. Async supported. |
CalendarImageExportOptions
| format?: 'png' | 'jpeg' | Image format. Default: 'png'. |
| quality?: number | JPEG quality (0-1). Default: 0.92. |
| scale?: number | Pixel scale factor. Default: 2. |
| includeSidebar?: boolean | Whether to include the sidebar. Default: false. |
CalendarPdfExportOptions
| pageSize?: 'A4' | 'A3' | 'Letter' | 'Legal' | Page format. Default: 'A4'. |
| orientation?: 'portrait' | 'landscape' | Page orientation. Default: 'landscape'. |
| margin?: { top, right, bottom, left } | Page margins in mm. Default: 10mm all sides. |
| header?: string | ((page, total) => string) | Header text on each page. |
| footer?: string | ((page, total) => string) | Footer text on each page. |
| quality?: number | Image quality (0-1). Default: 0.92. |
| scale?: number | Pixel scale factor. Default: 2. |
| includeSidebar?: boolean | Whether to include the sidebar. Default: false. |
CalendarIcsExportOptions
| calendarIds?: string[] | Which calendars to export. Default: all. |
| prodId?: string | PRODID value. Default: '-//TimelineKit//EventCalendar//EN'. |
| includeCustomType?: boolean | Include X-TIMELINEKIT-TYPE property. Default: true. |
CalendarCsvExportOptions
| delimiter?: ',' | ';' | '\t' | Column delimiter. Default: ','. |
| includeHeaders?: boolean | Include column headers. Default: true. |
| includeCalendars?: boolean | Include a calendars section. Default: false. |
| calendarIds?: string[] | Export only these calendars. Default: all. |
CalendarExcelExportOptions
| eventsSheetName?: string | Name of the events sheet. Default: locale-dependent. |
| includeCalendarsSheet?: boolean | Include a sheet listing calendars. Default: true. |
| includeFormatting?: boolean | Apply formatting (bold headers, column widths, frozen row). Default: true. |
| calendarIds?: string[] | Export only these calendars. Default: all. |
CalendarIcsImportOptions
| calendarId?: string | Calendar ID to assign to imported items. Default: from X-TIMELINEKIT-CALENDAR or null. |
| createCalendar?: boolean | Create a Calendar from VCALENDAR metadata. Default: true. |
| defaultType?: CalendarItemType | Default item type when X-TIMELINEKIT-TYPE is absent. Default: 'appointment'. |
CalendarIcsImportResult
| calendar: Calendar | null | Created calendar (if createCalendar was true and metadata was present). |
| items: CalendarItem[] | Imported items (master events with exceptions attached). |
| warnings: string[] | Non-fatal warnings encountered during parsing. |
| skippedCount: number | Count of skipped components (unsupported types, parse errors). |
ViewMode
| 'month' | Monthly grid view. |
| 'week' | Weekly time-grid view (default). |
| 'day' | Single-day time-grid view. |
| 'agenda' | Scrollable list of upcoming entries. |
RecurrenceFrequency
| 'daily' | Repeats every N days. |
| 'weekly' | Repeats every N weeks. |
| 'monthly' | Repeats every N months. |
| 'yearly' | Repeats every N years. |
Weekday
| 'mo' | 'tu' | 'we' | 'th' | 'fr' | 'sa' | 'su' | Day of the week (lowercase two-letter codes). |
WeekdayOrdinal
| day: Weekday | Day of the week. |
| ordinal?: number | Position within the month (1-5, or -1 for last, -2 for second-to-last). |
CalendarItemVisibility
| 'public' | Full content visible to everyone with calendar access. |
| 'private' | Others see only 'Busy' and the time, not title/description. |
| 'confidential' | Others don't see the item (only aggregated free/busy). |
ResponseStatus
| 'accepted' | Invitation accepted. |
| 'tentative' | Tentatively accepted. |
| 'declined' | Invitation declined. |
| 'needsAction' | No response yet (default). |
AvailabilityStatus
| 'busy' | Busy (default). |
| 'free' | Free / available. |
| 'tentative' | Tentatively busy. |
| 'outOfOffice' | Out of office. |
| 'workingElsewhere' | Working from another location. |
| 'focus' | Focus time / do not disturb. |
ExternalSource
| 'native' | 'google' | 'outlook' | 'apple' | Common calendar providers. |
| 'caldav' | 'ical' | 'office365' | 'exchange' | Protocol / platform sources. |
Shared Types
| ColorValue | number (palette index) | ColorDefinition (custom color object). |
| ColorDefinition | { color1: string, color2: string } — gradient/accent colors for entries. |
| EventCalendarEntryColor | Resolved color palette: color1, color2, textColor, chipBackgroundColor, chipTextColor. |
| CustomProperty | { name: string, value: any } — custom key-value property on items. |
| TimeRange | { start: Date, end: Date } — time range for entry expansion. |
EventCalendarTheme
| font: Font | Default font. Default: system font stack. |
| colorScheme: 'light' | 'dark' | Color scheme hint for native elements. |
| toolbar: EventCalendarToolbarStyle | Toolbar area styles (background, buttons, height). |
| header: EventCalendarHeaderStyle | Day header styles (today highlight, weekend color). |
| content: EventCalendarContentStyle | Main content area (grid, entries, time indicators, slots). |
| sidebar: EventCalendarSidebarStyle | Sidebar styles (mini calendar, calendar list). |
| allDay: EventCalendarAllDayStyle | All-day section styles (min/max height, row height). |
| timeGutter: EventCalendarTimeGutterStyle | Time gutter styles (width, font size, colors). |