@ebarooni/capacitor-calendar NPM

Installation

npm install @ebarooni/capacitor-calendar
npx cap sync

Demo

iOS 18	Android 15

Setup

This plugin requires additional platform-specific configuration. Follow the official guides:

iOS: Migrating to the Latest Calendar Access Levels
Android: Calendar Provider User Permissions

Documentation

For comprehensive usage examples, detailed explanations, and API references, check out:

Online documentation
Type definitions & examples

Changelog

See CHANGELOG.md for the latest updates and release history.

!NOTE
Version 7.1.0 introduces breaking changes.

API

checkPermission(...)

checkPermission(options: { scope: CalendarPermissionScope; }) => Promise<{ result: PermissionState; }>

Retrieves the current permission state for a given scope.

Param	Type
`options`	{ scope: CalendarPermissionScope; }

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

Platform: Android, iOS

checkAllPermissions()

checkAllPermissions() => Promise<{ result: CheckAllPermissionsResult; }>

Retrieves the current state of all permissions.

Returns: Promise<{ result: CheckAllPermissionsResult; }>

Since: 0.1.0

Platform: Android, iOS

requestPermission(...)

requestPermission(options: { scope: CalendarPermissionScope; }) => Promise<{ result: PermissionState; }>

Requests permission for a given scope.

Param	Type
`options`	{ scope: CalendarPermissionScope; }

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

Platform: Android, iOS

requestAllPermissions()

requestAllPermissions() => Promise<{ result: RequestAllPermissionsResult; }>

Requests permission for all calendar and reminder permissions.

Returns: Promise<{ result: CheckAllPermissionsResult; }>

Since: 0.1.0

Platform: Android, iOS

requestWriteOnlyCalendarAccess()

requestWriteOnlyCalendarAccess() => Promise<{ result: PermissionState; }>

Requests write access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: Android, iOS

requestReadOnlyCalendarAccess()

requestReadOnlyCalendarAccess() => Promise<{ result: PermissionState; }>

Requests read access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: Android

requestFullCalendarAccess()

requestFullCalendarAccess() => Promise<{ result: PermissionState; }>

Requests read and write access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: Android, iOS

requestFullRemindersAccess()

requestFullRemindersAccess() => Promise<{ result: PermissionState; }>

Requests read and write access to the reminders.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: iOS

createEventWithPrompt(...)

createEventWithPrompt(options?: CreateEventWithPromptOptions | undefined) => Promise<{ id: string | null; }>

Opens the system calendar interface to create a new event. On Android always returns null. Fetch the events to find the ID of the newly created event.

Param	Type
`options`	CreateEventWithPromptOptions

Returns: Promise<{ id: string | null; }>

Since: 0.1.0

Platform: Android, iOS

modifyEventWithPrompt(...)

modifyEventWithPrompt(options: ModifyEventWithPromptOptions) => Promise<{ result: EventEditAction | null; }>

Opens a system calendar interface to modify an event. On Android always returns null.

Param	Type
`options`	ModifyEventWithPromptOptions

Returns: Promise<{ result: EventEditAction | null; }>

Since: 6.6.0

Platform: Android, iOS

createEvent(...)

createEvent(options: CreateEventOptions) => Promise<{ id: string; }>

Creates an event in the calendar.

Param	Type
`options`	CreateEventOptions

Returns: Promise<{ id: string; }>

Since: 0.4.0

Platform: iOS, Android

modifyEvent(...)

modifyEvent(options: ModifyEventOptions) => Promise<void>

Modifies an event.

Param	Type
`options`	ModifyEventOptions

Since: 6.6.0

Platform: Android, iOS

deleteEventsById(...)

deleteEventsById(options: DeleteEventsByIdOptions) => Promise<{ result: DeleteEventsByIdResult; }>

Deletes multiple events.

Param	Type
`options`	DeleteEventsByIdOptions

Returns: Promise<{ result: DeleteEventsByIdResult; }>

Since: 0.11.0

Platform: Android, iOS

deleteEvent(...)

deleteEvent(options: DeleteEventOptions) => Promise<void>

Deletes an event.

Param	Type
`options`	DeleteEventOptions

Since: 7.1.0

Platform: Android, iOS

deleteEventWithPrompt(...)

deleteEventWithPrompt(options: DeleteEventWithPromptOptions) => Promise<{ deleted: boolean; }>

Opens a dialog to delete an event.

Param	Type
`options`	DeleteEventWithPromptOptions

Returns: Promise<{ deleted: boolean; }>

Since: 7.1.0

Platform: Android, iOS

listEventsInRange(...)

listEventsInRange(options: ListEventsInRangeOptions) => Promise<{ result: CalendarEvent[]; }>

Retrieves the events within a date range.

Param	Type
`options`	ListEventsInRangeOptions

Returns: Promise<{ result: CalendarEvent[]; }>

Since: 0.10.0

Platform: Android, iOS

commit()

commit() => Promise<void>

Save the changes to the calendar.

Since: 7.1.0

Platform: iOS

selectCalendarsWithPrompt(...)

selectCalendarsWithPrompt(options?: SelectCalendarsWithPromptOptions | undefined) => Promise<{ result: Calendar[]; }>

Opens a system interface to choose one or multiple calendars.

Param	Type
`options`	SelectCalendarsWithPromptOptions

Returns: Promise<{ result: Calendar[]; }>

Since: 0.2.0

Platform: iOS

fetchAllCalendarSources()

fetchAllCalendarSources() => Promise<{ result: CalendarSource[]; }>

Retrieves a list of calendar sources.

Returns: Promise<{ result: CalendarSource[]; }>

Since: 6.6.0

Platform: iOS

listCalendars()

listCalendars() => Promise<{ result: Calendar[]; }>

Retrieves a list of all available calendars.

Returns: Promise<{ result: Calendar[]; }>

Since: 7.1.0

Platform: Android, iOS

getDefaultCalendar()

getDefaultCalendar() => Promise<{ result: Calendar | null; }>

Retrieves the default calendar.

Returns: Promise<{ result: Calendar | null; }>

Since: 0.3.0

Platform: Android, iOS

openCalendar(...)

openCalendar(options?: OpenCalendarOptions | undefined) => Promise<void>

Opens the calendar app.

Param	Type
`options`	OpenCalendarOptions

Since: 7.1.0

Platform: Android, iOS

createCalendar(...)

createCalendar(options: CreateCalendarOptions) => Promise<{ id: string; }>

Creates a calendar.

Param	Type
`options`	CreateCalendarOptions

Returns: Promise<{ id: string; }>

Since: 5.2.0

Platform: Android, iOS

deleteCalendar(...)

deleteCalendar(options: DeleteCalendarOptions) => Promise<void>

Deletes a calendar by id.

Param	Type
`options`	DeleteCalendarOptions

Since: 5.2.0

Platform: Android, iOS

modifyCalendar(...)

modifyCalendar(options: ModifyCalendarOptions) => Promise<void>

Modifies a calendar with options.

Param	Type
`options`	ModifyCalendarOptions

Since: 7.2.0

Platform: Android, iOS

fetchAllRemindersSources()

fetchAllRemindersSources() => Promise<{ result: CalendarSource[]; }>

Retrieves a list of calendar sources.

Returns: Promise<{ result: CalendarSource[]; }>

Since: 6.6.0

Platform: iOS

openReminders()

openReminders() => Promise<void>

Opens the reminders app.

Since: 7.1.0

Platform: iOS

getDefaultRemindersList()

getDefaultRemindersList() => Promise<{ result: RemindersList | null; }>

Retrieves the default reminders list.

Returns: Promise<{ result: Calendar | null; }>

Since: 7.1.0

Platform: iOS

getRemindersLists()

getRemindersLists() => Promise<{ result: RemindersList[]; }>

Retrieves all available reminders lists.

Returns: Promise<{ result: Calendar[]; }>

Since: 7.1.0

Platform: iOS

createReminder(...)

createReminder(options: CreateReminderOptions) => Promise<{ id: string; }>

Creates a reminder.

Param	Type
`options`	CreateReminderOptions

Returns: Promise<{ id: string; }>

Since: 0.5.0

Platform: iOS

deleteRemindersById(...)

deleteRemindersById(options: DeleteRemindersByIdOptions) => Promise<{ result: DeleteRemindersByIdResult; }>

Deletes multiple reminders.

Param	Type
`options`	DeleteRemindersByIdOptions

Returns: Promise<{ result: DeleteRemindersByIdResult; }>

Since: 5.3.0

Platform: iOS

deleteReminder(...)

deleteReminder(options: DeleteReminderOptions) => Promise<void>

Deletes a reminder.

Param	Type
`options`	DeleteReminderOptions

Since: 7.1.0

Platform: iOS

modifyReminder(...)

modifyReminder(options: ModifyReminderOptions) => Promise<void>

Modifies a reminder.

Param	Type
`options`	ModifyReminderOptions

Since: 6.7.0

Platform: iOS

getReminderById(...)

getReminderById(options: GetReminderByIdOptions) => Promise<{ result: Reminder | null; }>

Retrieve a reminder by ID.

Param	Type
`options`	GetReminderByIdOptions

Returns: Promise<{ result: Reminder | null; }>

Since: 7.1.0

Platform: iOS

getRemindersFromLists(...)

getRemindersFromLists(options: GetRemindersFromListsOptions) => Promise<{ result: Reminder[]; }>

Retrieves reminders from multiple lists.

Param	Type
`options`	GetRemindersFromListsOptions

Returns: Promise<{ result: Reminder[]; }>

Since: 5.3.0

Platform: iOS

deleteReminderWithPrompt(...)

deleteReminderWithPrompt(options: DeleteReminderWithPromptOptions) => Promise<{ deleted: boolean; }>

Opens a dialog to delete a reminder.

Param	Type
`options`	DeleteReminderWithPromptOptions

Returns: Promise<{ deleted: boolean; }>

Since: 7.2.0

Platform: iOS

Interfaces

CreateEventWithPromptOptions

Prop	Type	Description	Since	Platform
`title`	string		0.1.0	Android, iOS
`calendarId`	string		0.1.0	iOS
`location`	string		0.1.0	Android, iOS
`startDate`	number		0.1.0	Android, iOS
`endDate`	number		0.1.0	Android, iOS
`isAllDay`	boolean		0.1.0	Android, iOS
`alerts`	number[]	Sets alerts before or after the start of the event in minutes. On iOS only 2 alerts are supported.	7.1.0	iOS
`url`	string		0.1.0	iOS
`description`	string		7.1.0	Android, iOS
`availability`	EventAvailability		7.1.0	Android, iOS
`invitees`	string[]	An array of emails to invite.	7.1.0	Android

ModifyEventWithPromptOptions

Prop	Type	Description	Since	Platform
`title`	string		0.1.0	Android, iOS
`calendarId`	string		0.1.0	iOS
`location`	string		0.1.0	Android, iOS
`startDate`	number		0.1.0	Android, iOS
`endDate`	number		0.1.0	Android, iOS
`isAllDay`	boolean		0.1.0	Android, iOS
`alerts`	number[]	Sets alerts before or after the start of the event in minutes. On iOS only 2 alerts are supported.	7.1.0	iOS
`url`	string		0.1.0	iOS
`description`	string		7.1.0	Android, iOS
`availability`	EventAvailability		7.1.0	Android, iOS
`invitees`	string[]	An array of emails to invite.	7.1.0	Android
`id`	string	The ID of the event to be modified.	7.1.0	Android, iOS

CreateEventOptions

Prop	Type	Description	Default	Since	Platform
`title`	string			0.4.0	Android, iOS
`calendarId`	string			0.1.0	Android, iOS
`location`	string			0.1.0	Android, iOS
`startDate`	number			0.1.0	Android, iOS
`endDate`	number			0.1.0	Android, iOS
`isAllDay`	boolean			0.1.0	Android, iOS
`alerts`	number[]			7.1.0	Android, iOS
`url`	string			0.1.0	iOS
`description`	string			7.1.0	Android, iOS
`availability`	EventAvailability			7.1.0	Android, iOS
`organizer`	string	Email of the event organizer.		7.1.0	Android
`color`	string			7.1.0	Android
`duration`	string	Duration of the event in RFC2445 format.		7.1.0	Android
`commit`	boolean	Whether to save immediately (`true`) or batch changes for later (`false`).	true	7.1.0	iOS
`attendees`	EventGuest[]	The event guests.		7.1.0	Android

EventGuest

Prop	Type	Since
`name`	string	7.1.0
`email`	string	7.1.0

ModifyEventOptions

Prop	Type	Description	Default	Since	Platform
`id`	string	The ID of the event to be modified.		7.1.0	Android, iOS
`title`	string			0.4.0	Android, iOS
`calendarId`	string			0.1.0	Android, iOS
`location`	string			0.1.0	Android, iOS
`startDate`	number			0.1.0	Android, iOS
`endDate`	number			0.1.0	Android, iOS
`isAllDay`	boolean			0.1.0	Android, iOS
`alerts`	number[]			7.1.0	Android, iOS
`url`	string			0.1.0	iOS
`description`	string			7.1.0	Android, iOS
`availability`	EventAvailability			7.1.0	Android, iOS
`organizer`	string	Email of the event organizer.		7.1.0	Android
`color`	string			7.1.0	Android
`duration`	string	Duration of the event in RFC2445 format.		7.1.0	Android
`attendees`	EventGuest[]	The event guests.		7.1.0	Android
`span`	EventSpan	The span of modifications.	EventSpan.THIS_EVENT		iOS

DeleteEventsByIdResult

Prop	Type	Since
`deleted`	string[]	7.1.0
`failed`	string[]	7.1.0

DeleteEventsByIdOptions

Prop	Type	Description	Default	Since	Platform
`ids`	string[]			7.1.0
`span`	EventSpan	The span of deletion.	EventSpan.THIS_EVENT		iOS

DeleteEventOptions

Prop	Type	Description	Default	Since	Platform
`id`	string			7.1.0
`span`	EventSpan	The span of deletion.	EventSpan.THIS_EVENT		iOS

DeleteEventWithPromptOptions

Prop	Type	Description	Default	Since	Platform
`id`	string			7.1.0
`span`	EventSpan	The span of deletion.	EventSpan.THIS_EVENT		iOS
`title`	string	Title of the dialog.		7.1.0	Android, iOS
`message`	string	Message of the dialog.		7.1.0	Android, iOS
`confirmButtonText`	string	Text to show on the confirm button.	'Delete'	7.1.0	Android, iOS
`cancelButtonText`	string	Text to show on the cancel button.	'Cancel'	7.1.0	Android, iOS

CalendarEvent

Prop	Type	Since	Platform
`id`	string	7.1.0	Android, iOS
`title`	string	7.1.0	Android, iOS
`calendarId`	string \| null	7.1.0	Android, iOS
`location`	string \| null	7.1.0	Android, iOS
`startDate`	number	7.1.0	Android, iOS
`endDate`	number	7.1.0	Android, iOS
`isAllDay`	boolean	7.1.0	Android, iOS
`alerts`	number[]	7.1.0	Android, iOS
`url`	string \| null	7.1.0	iOS
`description`	string \| null	7.1.0	Android, iOS
`availability`	EventAvailability \| null	7.1.0	Android, iOS
`organizer`	string \| null	7.1.0	Android, iOS
`color`	string \| null	7.1.0	Android, iOS
`duration`	string \| null	7.1.0	Android
`isDetached`	boolean \| null	7.1.0	iOS
`birthdayContactIdentifier`	string \| null	7.1.0	iOS
`status`	EventStatus \| null	7.1.0	Android, iOS
`creationDate`	number \| null	7.1.0	iOS
`lastModifiedDate`	number \| null	7.1.0	iOS
`attendees`	{ email: string \| null; name: string \| null; role: AttendeeRole \| null; status: AttendeeStatus \| null; type: AttendeeType \| null; }[]	7.1.0	Android, iOS
`timezone`	string \| null	7.1.0	Android, iOS

ListEventsInRangeOptions

Prop	Type	Description	Since
`from`	number	The timestamp in milliseconds.	7.1.0
`to`	number	The timestamp in milliseconds.	7.1.0

Calendar

Prop	Type	Description	Since	Platform
`id`	string		7.1.0	Android, iOS
`title`	string		7.1.0	Android, iOS
`internalTitle`	string \| null	Internal name of the calendar (`CalendarContract.Calendars.NAME`).	7.1.0	Android
`color`	string		7.1.0	Android, iOS
`isImmutable`	boolean \| null		7.1.0	iOS
`allowsContentModifications`	boolean \| null		7.1.0	iOS
`type`	CalendarType \| null		7.1.0	iOS
`isSubscribed`	boolean \| null		7.1.0	iOS
`source`	CalendarSource \| null		7.1.0	iOS
`visible`	boolean \| null	Indicates if the events from this calendar should be shown.	7.1.0	Android
`accountName`	string \| null	The account under which the calendar is registered.	7.1.0	Android
`ownerAccount`	string \| null	The owner of the calendar.	7.1.0	Android
`maxReminders`	number \| null	Maximum number of reminders allowed per event.	7.1.0	Android
`location`	string \| null		7.1.0	Android

CalendarSource

Prop	Type	Since
`type`	CalendarSourceType	7.1.0
`id`	string	7.1.0
`title`	string	7.1.0

SelectCalendarsWithPromptOptions

Prop	Type	Description	Default	Since
`displayStyle`	CalendarChooserDisplayStyle		CalendarChooserDisplayStyle.ALL_CALENDARS	7.1.0
`multiple`	boolean	Allow multiple selections.	false	7.1.0

OpenCalendarOptions

Prop	Type	Default	Since
`date`	number	Date.now()	7.1.0

CreateCalendarOptions

Prop	Type	Description	Since	Platform
`title`	string		5.2.0	Android, iOS
`color`	string	The color of the calendar. Should be provided on Android.	5.2.0	Android, iOS
`sourceId`	string		5.2.0	iOS
`accountName`	string	Only needed on Android. Typically set to an email address.	7.1.0	Android
`ownerAccount`	string	Only needed on Android. Typically set to an email address.	7.1.0	Android

DeleteCalendarOptions

Prop	Type	Since
`id`	string	7.1.0

ModifyCalendarOptions

Prop	Type	Since	Platform
`id`	string	7.2.0	Android, iOS
`title`	string	7.2.0	Android, iOS
`color`	string	7.2.0	Android, iOS

CreateReminderOptions

Prop	Type	Since
`title`	string	7.1.0
`listId`	string	7.1.0
`priority`	number	7.1.0
`isCompleted`	boolean	7.1.0
`startDate`	number	7.1.0
`dueDate`	number	7.1.0
`completionDate`	number	7.1.0
`notes`	string	7.1.0
`url`	string	7.1.0
`location`	string	7.1.0
`recurrence`	RecurrenceRule	7.1.0
`alerts`	number[]	7.1.0

RecurrenceRule

Prop	Type	Description	Since
`frequency`	RecurrenceFrequency		7.1.0
`interval`	number	How often it repeats (e.g. 1 for every occurrence, 2 for every second occurrence).	7.1.0
`end`	number	Timestamp of when the recurrence ends.	7.1.0

DeleteRemindersByIdResult

Prop	Type	Since
`deleted`	string[]	7.1.0
`failed`	string[]	7.1.0

DeleteRemindersByIdOptions

Prop	Type	Since
`ids`	string[]	7.1.0

DeleteReminderOptions

Prop	Type	Since
`id`	string	7.1.0

ModifyReminderOptions

Prop	Type	Since
`id`	string	7.1.0
`title`	string	7.1.0
`listId`	string	7.1.0
`priority`	number	7.1.0
`isCompleted`	boolean	7.1.0
`startDate`	number	7.1.0
`dueDate`	number	7.1.0
`completionDate`	number	7.1.0
`notes`	string	7.1.0
`url`	string	7.1.0
`location`	string	7.1.0
`recurrence`	RecurrenceRule	7.1.0
`alerts`	number[]	7.1.0

Reminder

Prop	Type	Since
`id`	string	7.1.0
`title`	string \| null	7.1.0
`listId`	string \| null	7.1.0
`isCompleted`	boolean	7.1.0
`priority`	number \| null	7.1.0
`notes`	string \| null	7.1.0
`location`	string \| null	7.1.0
`url`	string \| null	7.1.0
`startDate`	number \| null	7.1.0
`dueDate`	number \| null	7.1.0
`completionDate`	number \| null	7.1.0
`recurrence`	RecurrenceRule[]	7.1.0
`alerts`	number[]	7.1.0

GetReminderByIdOptions

Prop	Type	Since
`id`	string	7.1.0

GetRemindersFromListsOptions

Prop	Type	Since
`listIds`	string[]	7.1.0

DeleteReminderWithPromptOptions

Prop	Type	Description	Default	Since
`id`	string			7.2.0
`title`	string	Title of the dialog.		7.2.0
`message`	string	Message of the dialog.		7.2.0
`confirmButtonText`	string	Text to show on the confirm button.	'Delete'	7.2.0
`cancelButtonText`	string	Text to show on the cancel button.	'Cancel'	7.2.0

Type Aliases

PermissionState

'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'

CheckAllPermissionsResult

Record< CalendarPermissionScope, PermissionState >

Record

Construct a type with a set of properties K of type T

{

}

RequestAllPermissionsResult

CheckAllPermissionsResult

EventEditAction

"canceled" | "saved" | "deleted"

RemindersList

Calendar

Enums

CalendarPermissionScope

Members	Value	Description	Since	Platform
`READ_CALENDAR`	"readCalendar"	Permission required for reading calendar events.	7.1.0	Android, iOS
`READ_REMINDERS`	"readReminders"	Permission required for reading reminders.	7.1.0	iOS
`WRITE_CALENDAR`	"writeCalendar"	Permission required for adding or modifying calendar events.	7.1.0	Android, iOS
`WRITE_REMINDERS`	"writeReminders"	Permission required for adding or modifying reminders.	7.1.0	iOS

EventAvailability

Members	Value	Since	Platform
`NOT_SUPPORTED`	-1	7.1.0	iOS
`BUSY`		7.1.0	Android, iOS
`FREE`		7.1.0	Android, iOS
`TENTATIVE`		7.1.0	Android, iOS
`UNAVAILABLE`		7.1.0	iOS

EventSpan

Members	Since
`THIS_EVENT`	7.1.0
`THIS_AND_FUTURE_EVENTS`	7.1.0

EventStatus

Members	Value	Since	Platform
`NONE`	"none"	7.1.0	iOS
`CONFIRMED`	"confirmed"	7.1.0	Android, iOS
`TENTATIVE`	"tentative"	7.1.0	Android, iOS
`CANCELED`	"canceled"	7.1.0	Android, iOS

AttendeeRole

Members	Value	Since	Platform
`UNKNOWN`	"unknown"	7.1.0	Android, iOS
`REQUIRED`	"required"	7.1.0	iOS
`OPTIONAL`	"optional"	7.1.0	iOS
`CHAIR`	"chair"	7.1.0	iOS
`NON_PARTICIPANT`	"nonParticipant"	7.1.0	Android, iOS
`ATTENDEE`	"attendee"	7.1.0	Android
`ORGANIZER`	"organizer"	7.1.0	Android
`PERFORMER`	"performer"	7.1.0	Android
`SPEAKER`	"speaker"	7.1.0	Android

AttendeeStatus

Members	Value	Since	Platform
`NONE`	"none"	7.1.0	Android
`ACCEPTED`	"accepted"	7.1.0	Android, iOS
`DECLINED`	"declined"	7.1.0	Android, iOS
`INVITED`	"invited"	7.1.0	Android
`UNKNOWN`	"unknown"	7.1.0	iOS
`PENDING`	"pending"	7.1.0	iOS
`TENTATIVE`	"tentative"	7.1.0	Android, iOS
`DELEGATED`	"delegated"	7.1.0	iOS
`COMPLETED`	"completed"	7.1.0	iOS
`IN_PROCESS`	"inProcess"	7.1.0	iOS

AttendeeType

Members	Value	Since	Platform
`UNKNOWN`	"unknown"	7.1.0	Android, iOS
`PERSON`	"person"	7.1.0	iOS
`ROOM`	"room"	7.1.0	iOS
`RESOURCE`	"resource"	7.1.0	Android, iOS
`GROUP`	"group"	7.1.0	iOS
`REQUIRED`	"required"	7.1.0	Android
`NONE`	"none"	7.1.0	Android
`OPTIONAL`	"optional"	7.1.0	Android