A capacitor plugin for managing calendar events on iOS and Android, with reminders support on iOS.
npm install @ebarooni/capacitor-calendar
npx cap sync| iOS 17 | Android 14 |
|---|---|
 |
 |
This plugin requires additional platform-specific configuration. Follow the official guides:
For comprehensive usage examples, detailed explanations, and API references, check out:
checkPermission(...)checkAllPermissions()requestPermission(...)requestAllPermissions()requestWriteOnlyCalendarAccess()requestReadOnlyCalendarAccess()requestFullCalendarAccess()createEventWithPrompt(...)requestFullRemindersAccess()selectCalendarsWithPrompt(...)listCalendars()getDefaultCalendar()createEvent(...)getDefaultRemindersList()getRemindersLists()createReminder(...)openCalendar(...)openReminders()listEventsInRange(...)deleteEventsById(...)createCalendar(...)deleteCalendar(...)getRemindersFromLists(...)deleteRemindersById(...)modifyEventWithPrompt(...)modifyEvent(...)fetchAllCalendarSources()fetchAllRemindersSources()modifyReminder(...)- Interfaces
- Type Aliases
- Enums
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
checkAllPermissions() => Promise<{ result: CheckAllPermissionsResult; }>Retrieves the current state of all permissions.
Returns: Promise<{ result: CheckAllPermissionsResult; }>
Since: 0.1.0
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
requestAllPermissions() => Promise<{ result: RequestAllPermissionsResult; }>Requests permission for all calendar and reminder permissions.
Returns: Promise<{ result: CheckAllPermissionsResult; }>
Since: 0.1.0
requestWriteOnlyCalendarAccess() => Promise<{ result: PermissionState; }>Requests write access to the calendar.
Returns: Promise<{ result: PermissionState; }>
Since: 5.4.0
requestReadOnlyCalendarAccess() => Promise<{ result: PermissionState; }>Requests read access to the calendar.
Returns: Promise<{ result: PermissionState; }>
Since: 5.4.0
requestFullCalendarAccess() => Promise<{ result: PermissionState; }>Requests read and write access to the calendar.
Returns: Promise<{ result: PermissionState; }>
Since: 5.4.0
createEventWithPrompt(options?: CreateEventWithPromptOptions | undefined) => Promise<{ id: string | null; }>Opens the system calendar interface to create a new event.
On Android returns always 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
requestFullRemindersAccess() => Promise<{ result: PermissionState; }>Requests read and write access to the reminders.
Returns: Promise<{ result: PermissionState; }>
Since: 5.4.0
selectCalendarsWithPrompt(options: { displayStyle: CalendarChooserDisplayStyle; selectionStyle: CalendarChooserSelectionStyle; }) => Promise<{ result: Calendar[]; }>Presents a prompt to the user to select calendars. This method is available only on iOS.
| Param | Type | Description |
|---|---|---|
options |
{ displayStyle: CalendarChooserDisplayStyle; selectionStyle: CalendarChooserSelectionStyle; } |
- Options for customizing the display and selection styles of the calendar chooser. |
Returns: Promise<{ result: Calendar[]; }>
Since: 0.2.0
listCalendars() => Promise<{ result: Calendar[]; }>Retrieves a list of calendars available on the device.
Returns: Promise<{ result: Calendar[]; }>
getDefaultCalendar() => Promise<{ result: Calendar | null; }>Retrieves the default calendar set on the device.
Returns: Promise<{ result: Calendar | null; }>
Since: 0.3.0
createEvent(options: { title: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; }) => Promise<{ result: string; }>Creates an event with the provided options.
| Param | Type | Description |
|---|---|---|
options |
{ title: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; } |
Options for creating the event. |
Returns: Promise<{ result: string; }>
Since: 0.4.0
getDefaultRemindersList() => Promise<{ result: RemindersList; }>Retrieves the default reminders list set on the device.
Returns: Promise<{ result: Calendar; }>
getRemindersLists() => Promise<{ result: RemindersList[]; }>Retrieves all available reminders lists on the device.
Returns: Promise<{ result: Calendar[]; }>
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
openCalendar(options: { date?: number; }) => Promise<void>Opens the calendar app. Since the user leaves your app, use this method with caution. It will open the calendar on today's date if no date is provided.
| Param | Type | Description |
|---|---|---|
options |
{ date?: number; } |
- Options for opening the calendar. |
openReminders() => Promise<void>Opens the reminders app. Since the user leaves your app, use this method with caution.
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
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
createCalendar(options: { title: string; color?: string; sourceId?: string; }) => Promise<{ result: string; }>Creates a calendar
| Param | Type | Description |
|---|---|---|
options |
{ title: string; color?: string; sourceId?: string; } |
Options for creating a calendar. |
Returns: Promise<{ result: string; }>
Since: 5.2.0
deleteCalendar(options: { id: string; }) => Promise<void>Deletes a calendar by id
| Param | Type | Description |
|---|---|---|
options |
{ id: string; } |
Options for deleting a calendar. |
Since: 5.2.0
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
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
modifyEventWithPrompt(options: { id: string; update?: { title?: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; }; }) => Promise<{ result: string[]; }>Opens a native prompt to modify an event given its id.
| Param | Type | Description |
|---|---|---|
options |
{ id: string; update?: { title?: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; }; } |
The options for modifying an event. |
Returns: Promise<{ result: string[]; }>
Since: 6.6.0
modifyEvent(options: { id: string; span?: EventSpan; update: { title?: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; }; }) => Promise<void>Modifies an event given its id and update details.
| Param | Type | Description |
|---|---|---|
options |
{ id: string; span?: EventSpan; update: { title?: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; }; } |
The options for updating an event. |
Since: 6.6.0
fetchAllCalendarSources() => Promise<{ result: CalendarSource[]; }>Retrieves a list of calendar sources.
Returns: Promise<{ result: CalendarSource[]; }>
Since: 6.6.0
fetchAllRemindersSources() => Promise<{ result: CalendarSource[]; }>Retrieves a list of reminders sources.
Returns: Promise<{ result: CalendarSource[]; }>
Since: 6.6.0
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
| Prop | Type | Description | Since |
|---|---|---|---|
title |
string |
0.1.0 | |
calendarId |
string |
0.1.0 | |
location |
string |
0.1.0 | |
startDate |
number |
0.1.0 | |
endDate |
number |
0.1.0 | |
isAllDay |
boolean |
0.1.0 | |
alerts |
number[] |
Sets alerts before the start of the event in minutes. On iOS only 2 alerts are supported. | 7.1.0 |
url |
string |
0.1.0 | |
description |
string |
7.1.0 | |
availability |
EventAvailability |
||
invitees |
string[] |
An array of emails to invite. | 7.1.0 |
Represents a calendar object.
| Prop | Type |
|---|---|
id |
string |
title |
string |
color |
string |
isImmutable |
boolean |
allowsContentModifications |
boolean |
type |
CalendarType |
isSubscribed |
boolean |
source |
CalendarSource |
Represents the account a calendar belongs to
| Prop | Type |
|---|---|
type |
CalendarSourceType |
id |
string |
title |
string |
| 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. |
Represents an event in the calendar.
| Prop | Type |
|---|---|
id |
string |
title |
string |
location |
string |
eventColor |
string |
organizer |
string |
description |
string |
startDate |
number |
endDate |
number |
eventTimezone |
{ region: string; abbreviation: string; } |
eventEndTimezone |
{ region: string; abbreviation: string; } |
duration |
string |
isAllDay |
boolean |
calendarId |
string |
url |
string |
Represents a reminder in a reminders list.
| Prop | Type |
|---|---|
id |
string |
title |
string |
listId |
string |
isCompleted |
boolean |
priority |
number |
notes |
string |
location |
string |
url |
string |
startDate |
number |
dueDate |
number |
completionDate |
number |
recurrence |
ReminderRecurrenceRule[] |
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
Record< CalendarPermissionScope, PermissionState >
Construct a type with a set of properties K of type T
{
[P in K]: T;
}
| Members | Value | Description | Since |
|---|---|---|---|
READ_CALENDAR |
"readCalendar" |
Permission required for reading calendar events. | 7.1.0 |
READ_REMINDERS |
"readReminders" |
Permission required for reading reminders. | 7.1.0 |
WRITE_CALENDAR |
"writeCalendar" |
Permission required for adding or modifying calendar events. | 7.1.0 |
WRITE_REMINDERS |
"writeReminders" |
Permission required for adding or modifying reminders. | 7.1.0 |
| Members | Value | Since |
|---|---|---|
NOT_SUPPORTED |
-1 |
7.1.0 |
BUSY |
7.1.0 | |
FREE |
7.1.0 | |
TENTATIVE |
7.1.0 | |
UNAVAILABLE |
7.1.0 |
| Members | Description |
|---|---|
LOCAL |
This calendar is sync'd from either Mobile Me or tethered. |
CAL_DAV |
This calendar is from a CalDAV server. |
EXCHANGE |
This calendar comes from an Exchange server. |
SUBSCRIPTION |
This is a locally subscribed calendar. |
BIRTHDAY |
This is the built-in birthday calendar. |
| Members | Description |
|---|---|
LOCAL |
Calendars that are stored locally on the device. These calendars are not synced with any external service. |
EXCHANGE |
Calendars that are associated with an Exchange server. Exchange is a popular calendar and email service used by many enterprises. |
CAL_DAV |
Calendars that use the CalDAV protocol for synchronization. This includes calendars from services like Google Calendar and Yahoo Calendar. |
MOBILE_ME |
Calendars that were previously associated with MobileMe, Apple's cloud service before iCloud. This source type is largely obsolete now. |
SUBSCRIBED |
Calendars that the user has subscribed to. These are read-only calendars that can be added by subscribing to a calendar URL. |
BIRTHDAYS |
The built-in Birthdays calendar, which shows birthdays of contacts from the user's address book. This calendar is typically read-only and is managed by the system. |
| Members | Description |
|---|---|
ALL_CALENDARS |
Display all calendars available for selection. |
WRITABLE_CALENDARS_ONLY |
Display only writable calendars available for selection. |
| Members | Description |
|---|---|
SINGLE |
Allows only a single selection in the calendar chooser. |
MULTIPLE |
Allows multiple selections in the calendar chooser. |
| 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 |
| Members | Description |
|---|---|
THIS_EVENT |
The modifications should only be applied to this event. |
THIS_AND_FUTURE_EVENTS |
The modifications to this event should also be applied to the future instances of this event. |
See CHANGELOG.md for the latest updates and release history.
See CONTRIBUTING.md for guidelines.
This project is licensed under the MIT License. See LICENSE for details.