A capacitor plugin for managing calendar events on iOS and Android, with reminders support on iOS.
A capacitor plugin for managing calendar events on iOS and Android, with reminders support on iOS.
Table of Contents
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:
Documentation
For comprehensive usage examples, detailed explanations, and API references, check out:
API
checkPermission(...)checkAllPermissions()requestPermission(...)requestAllPermissions()requestWriteOnlyCalendarAccess()requestReadOnlyCalendarAccess()requestFullCalendarAccess()requestFullRemindersAccess()createEventWithPrompt(...)modifyEventWithPrompt(...)createEvent(...)modifyEvent(...)commit()selectCalendarsWithPrompt(...)fetchAllCalendarSources()listCalendars()getDefaultCalendar()openCalendar(...)createCalendar(...)deleteCalendar(...)fetchAllRemindersSources()openReminders()getDefaultRemindersList()getRemindersLists()createReminder(...)listEventsInRange(...)deleteEventsById(...)getRemindersFromLists(...)deleteRemindersById(...)modifyReminder(...)- Interfaces
- Type Aliases
- Enums
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
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
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: { title: string; listId?: string; priority?: number; isCompleted?: boolean; startDate?: number; dueDate?: number; completionDate?: number; notes?: string; url?: string; location?: string; recurrence?: ReminderRecurrenceRule; }) => Promise<{ result: string; }>
Creates a reminder with the provided options.
| Param | Type | Description |
|---|---|---|
options |
{ title: string; listId?: string; priority?: number; isCompleted?: boolean; startDate?: number; dueDate?: number; completionDate?: number; notes?: string; url?: string; location?: string; recurrence?: ReminderRecurrenceRule; } |
- Options for creating the reminder. |
Returns: Promise<{ result: string; }>
Since: 0.5.0
Platform: iOS
listEventsInRange(…)
listEventsInRange(options: { startDate: number; endDate: number; }) => Promise<{ result: CalendarEvent[]; }>
Retrieves the list of calendar events present in the given date range.
| Param | Type | Description |
|---|---|---|
options |
{ startDate: number; endDate: number; } |
Options for defining the date range. |
Returns: Promise<{ result: CalendarEvent[]; }>
Since: 0.10.0
Platform: iOS, Android
deleteEventsById(…)
deleteEventsById(options: { ids: string[]; }) => Promise<{ result: { deleted: string[]; failed: string[]; }; }>
Deletes events from the calendar given their IDs.
| Param | Type | Description |
|---|---|---|
options |
{ ids: string[]; } |
Options for defining event IDs. |
Returns: Promise<{ result: { deleted: string[]; failed: string[]; }; }>
Since: 0.11.0
Platform: iOS, Android
getRemindersFromLists(…)
getRemindersFromLists(options?: { listIds: string[]; } | undefined) => Promise<{ result: Reminder[]; }>
Retrieves the list of reminders present in the given date range.
| Param | Type | Description |
|---|---|---|
options |
{ listIds: string[]; } |
Options for defining the date range. It Will fetch all reminders from all available lists if not provided. (Optional) |
Returns: Promise<{ result: Reminder[]; }>
Since: 5.3.0
Platform: iOS
deleteRemindersById(…)
deleteRemindersById(options: { ids: string[]; }) => Promise<{ result: { deleted: string[]; failed: string[]; }; }>
Deletes reminders given their IDs.
| Param | Type | Description |
|---|---|---|
options |
{ ids: string[]; } |
Options for defining reminder IDs. |
Returns: Promise<{ result: { deleted: string[]; failed: string[]; }; }>
Since: 5.3.0
Platform: iOS
modifyReminder(…)
modifyReminder(options: { id: string; update: { title?: string; listId?: string; priority?: number; isCompleted?: boolean; startDate?: number; dueDate?: number; completionDate?: number; notes?: string; url?: string; location?: string; recurrence?: ReminderRecurrenceRule; }; }) => Promise<void>
Modifies a reminder given its id and update details.
| Param | Type | Description |
|---|---|---|
options |
{ id: string; update: { title?: string; listId?: string; priority?: number; isCompleted?: boolean; startDate?: number; dueDate?: number; completionDate?: number; notes?: string; url?: string; location?: string; recurrence?: ReminderRecurrenceRule; }; } |
The options for updating a reminder. |
Since: 6.7.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 |
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 |
ReminderRecurrenceRule
| Prop | Type | Description |
|---|---|---|
frequency |
ReminderRecurrenceFrequency |
How frequent should the reminder repeat. |
interval |
number |
The interval should be a number greater than 0. For values lower than 1 the method will throw an error. |
end |
number |
When provided, the reminder will stop repeating at the given time. |
CalendarEvent
Represents an event in the calendar.
| Prop | Type | Platform |
|---|---|---|
id |
string |
iOS, Android |
title |
string |
iOS, Android |
location |
string |
iOS, Android |
eventColor |
string |
iOS, Android |
organizer |
string |
iOS, Android |
description |
string |
iOS, Android |
startDate |
number |
iOS, Android |
endDate |
number |
iOS, Android |
eventTimezone |
{ region: string; abbreviation: string; } |
iOS, Android |
eventEndTimezone |
{ region: string; abbreviation: string; } |
iOS, Android |
duration |
string |
Android |
isAllDay |
boolean |
iOS, Android |
calendarId |
string |
iOS, Android |
url |
string |
iOS |
Reminder
Represents a reminder in a reminders list.
| Prop | Type | Platform |
|---|---|---|
id |
string |
iOS |
title |
string |
iOS |
listId |
string |
iOS |
isCompleted |
boolean |
iOS |
priority |
number |
iOS |
notes |
string |
iOS |
location |
string |
iOS |
url |
string |
iOS |
startDate |
number |
iOS |
dueDate |
number |
iOS |
completionDate |
number |
iOS |
recurrence |
ReminderRecurrenceRule[] |
iOS |
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
{
[P in K]: T;
}
RequestAllPermissionsResult
EventEditAction
“canceled” | “saved” | “deleted”
RemindersList
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 |
CalendarType
| Members | Since |
|---|---|
LOCAL |
7.1.0 |
CAL_DAV |
7.1.0 |
EXCHANGE |
7.1.0 |
SUBSCRIPTION |
7.1.0 |
BIRTHDAY |
7.1.0 |
CalendarSourceType
| Members | Since |
|---|---|
LOCAL |
7.1.0 |
EXCHANGE |
7.1.0 |
CAL_DAV |
7.1.0 |
MOBILE_ME |
7.1.0 |
SUBSCRIBED |
7.1.0 |
BIRTHDAYS |
7.1.0 |
CalendarChooserDisplayStyle
| Members | Since |
|---|---|
ALL_CALENDARS |
0.2.0 |
WRITABLE_CALENDARS_ONLY |
0.2.0 |
ReminderRecurrenceFrequency
| Members | Description |
|---|---|
DAILY |
The reminder repeats on a daily basis |
WEEKLY |
The reminder repeats on a weekly basis |
MONTHLY |
The reminder repeats on a monthly basis |
YEARLY |
The reminder repeats on a yearly basis |
Changelog
See CHANGELOG.md for the latest updates and release history.
Contributing
See CONTRIBUTING.md for guidelines.
License
This project is licensed under the MIT License. See LICENSE for details.