Create, find, modify and remove events in the device calendar.
To use npm
npm install @capacitor/calendarTo use yarn
yarn add @capacitor/calendarSync native files
npx cap syncAdd the calendar usage-description keys to your app's Info.plist; iOS
crashes on first calendar access without them. iOS 17 split calendar access
into two levels with their own keys; keep the pre-17 key for older devices:
<key>NSCalendarsFullAccessUsageDescription</key>
<string>We need access to your calendar to search, create and remove events.</string>
<key>NSCalendarsWriteOnlyAccessUsageDescription</key>
<string>We need access to your calendar to create events.</string>
<key>NSCalendarsUsageDescription</key>
<string>We need access to your calendar to search, create and remove events.</string>Notes:
- The plugin uses the current EventKit access APIs
(
requestFullAccessToEvents/requestWriteOnlyAccessToEventson iOS 17+), never the deprecatedrequestAccess(to:).writeCalendaris satisfied by write-only access ("Add Events Only");readCalendarrequires full access. createEventInteractivelypresents the system event editor, which on iOS 17+ needs no calendar permission at all.- EventKit stores dates at second granularity, so
startDate/endDateread back with milliseconds truncated. Android keeps exact milliseconds.
The plugin declares READ_CALENDAR and WRITE_CALENDAR in its own
manifest; Gradle manifest merging adds them to your app automatically.
Methods also request the runtime permission they need when it has not been
granted yet: read for findEvents/listCalendars, write for
createEvent/createCalendar, both for modifyEvent/deleteEvent/
deleteCalendar.
Platform notes:
createEventInteractivelyopens the system calendar editor, which reports neither the saved event's id nor a cancel, so the call resolves with an empty result when the editor closes.CreateEventOptions.urlis ignored: the platform's event model has no URL field.
Every rejection carries a structured code + message:
| Code | Meaning |
|---|---|
OS-PLUG-CLDR-0000 |
Unknown error |
OS-PLUG-CLDR-0001 |
Invalid argument (e.g. no matching event) |
OS-PLUG-CLDR-0003 |
Pending operation (e.g. editor already open) |
OS-PLUG-CLDR-0004 |
I/O error |
OS-PLUG-CLDR-0005 |
Not supported |
OS-PLUG-CLDR-0006 |
Operation cancelled (editor closed) |
OS-PLUG-CLDR-0020 |
Permission denied |
checkPermissions()requestPermissions(...)createEvent(...)createEventInteractively(...)modifyEvent(...)findEvents(...)deleteEvent(...)listCalendars()createCalendar(...)deleteCalendar(...)openCalendar(...)- Interfaces
- Type Aliases
checkPermissions() => Promise<CalendarPermissionStatus>Returns the current calendar permission state without prompting.
On iOS 17+, readCalendar reflects full access; writeCalendar is also
granted by write-only access ("Add Events Only").
Returns: Promise<CalendarPermissionStatus>
Since: 1.0.0
requestPermissions(options?: RequestPermissionsOptions | undefined) => Promise<CalendarPermissionStatus>Prompts for the given calendar permissions (both when omitted).
On iOS, requesting readCalendar prompts for full access; requesting only
writeCalendar prompts for write-only access on iOS 17+.
| Param | Type |
|---|---|
options |
RequestPermissionsOptions |
Returns: Promise<CalendarPermissionStatus>
Since: 1.0.0
createEvent(options: CreateEventOptions) => Promise<CreateEventResult>Creates a calendar event silently and resolves with its id.
Requires write permission; requests it when not yet determined.
| Param | Type |
|---|---|
options |
CreateEventOptions |
Returns: Promise<CreateEventResult>
Since: 1.0.0
createEventInteractively(options: CreateEventOptions) => Promise<CreateEventResult>Opens the system event-editing UI prefilled with the given values.
Resolves when the user saves (with the new event's id where the platform
provides one; Android does not) and fails with OS-PLUG-CLDR-0006 when
the user cancels.
On iOS 17+ the editor needs no calendar permission. On Android and older iOS versions, write permission is requested first.
| Param | Type |
|---|---|
options |
CreateEventOptions |
Returns: Promise<CreateEventResult>
Since: 1.0.0
modifyEvent(options: ModifyEventOptions) => Promise<void>Updates the first event matching filter with the values in newEvent.
Only the fields present in newEvent are changed. Fails with
OS-PLUG-CLDR-0001 when no event matches.
Requires read and write permission.
| Param | Type |
|---|---|
options |
ModifyEventOptions |
Since: 1.0.0
findEvents(options: FindEventsOptions) => Promise<FindEventsResult>Returns events matching the filter fields within the date range.
title, location and notes match case-insensitive substrings;
calendarName restricts the search to that calendar. A recurring
event is returned once per occurrence in the range, each with its
own dates.
Requires read permission.
| Param | Type |
|---|---|
options |
FindEventsOptions |
Returns: Promise<FindEventsResult>
Since: 1.0.0
deleteEvent(options: DeleteEventOptions) => Promise<void>Deletes events: by id when given, otherwise every event matching the
filter fields. Fails with OS-PLUG-CLDR-0001 when nothing matches.
Deleting a recurring event removes the entire series.
Requires read and write permission.
| Param | Type |
|---|---|
options |
DeleteEventOptions |
Since: 1.0.0
listCalendars() => Promise<ListCalendarsResult>Returns the calendars available on the device.
Requires read permission.
Returns: Promise<ListCalendarsResult>
Since: 1.0.0
createCalendar(options: CreateCalendarOptions) => Promise<CreateCalendarResult>Creates a calendar and resolves with its id.
Requires write permission.
| Param | Type |
|---|---|
options |
CreateCalendarOptions |
Returns: Promise<CreateCalendarResult>
Since: 1.0.0
deleteCalendar(options: DeleteCalendarOptions) => Promise<void>Deletes the calendar with the given name. Fails with
OS-PLUG-CLDR-0001 when no calendar has that name.
Requires read and write permission.
| Param | Type |
|---|---|
options |
DeleteCalendarOptions |
Since: 1.0.0
openCalendar(options?: OpenCalendarOptions | undefined) => Promise<void>Opens the system calendar app at the given date (today when omitted). Needs no calendar permission.
| Param | Type |
|---|---|
options |
OpenCalendarOptions |
Since: 1.0.0
Permission state per calendar permission.
| Prop | Type | Description | Since |
|---|---|---|---|
readCalendar |
PermissionState |
Permission to read calendar events. | 1.0.0 |
writeCalendar |
PermissionState |
Permission to add events to the calendar. | 1.0.0 |
Options accepted by {@link CalendarPlugin.requestPermissions}.
| Prop | Type | Description | Since |
|---|---|---|---|
permissions |
CalendarPermissionType[] |
The permissions to request. Both are requested when omitted. | 1.0.0 |
Result of {@link CalendarPlugin.createEvent} and {@link CalendarPlugin.createEventInteractively}.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The created event's id. Absent when the platform does not report it (Android's interactive editor). | 1.0.0 |
Options accepted by {@link CalendarPlugin.createEvent} and {@link CalendarPlugin.createEventInteractively}, and the new values of {@link CalendarPlugin.modifyEvent}.
| Prop | Type | Description | Since |
|---|---|---|---|
title |
string |
The event title. | 1.0.0 |
location |
string |
The event location. | 1.0.0 |
notes |
string |
Free-form event notes. | 1.0.0 |
startDate |
number |
Event start as epoch milliseconds. | 1.0.0 |
endDate |
number |
Event end as epoch milliseconds. | 1.0.0 |
isAllDay |
boolean |
Whether the event lasts all day. | 1.0.0 |
calendarId |
string |
Id of the calendar to create the event in. Takes precedence over calendarName; the default calendar is used when neither is set. |
1.0.0 |
calendarName |
string |
Name of the calendar to create the event in. | 1.0.0 |
url |
string |
URL attached to the event. Android: the platform's event model has no URL field; the value is ignored. | 1.0.0 |
firstReminderMinutes |
number |
Minutes before the event for the first reminder. | 1.0.0 |
secondReminderMinutes |
number |
Minutes before the event for the second reminder. | 1.0.0 |
recurrence |
EventRecurrence |
Recurrence rule for a repeating event. | 1.0.0 |
Recurrence rule applied to a created event.
| Prop | Type | Description | Since |
|---|---|---|---|
frequency |
RecurrenceFrequency |
How often the event repeats. | 1.0.0 |
interval |
number |
Repeat every interval periods of frequency (default 1). |
1.0.0 |
endDate |
number |
Last possible date of a repetition, as epoch milliseconds. Mutually exclusive with count; endDate wins when both are set. |
1.0.0 |
count |
number |
Total number of repetitions. | 1.0.0 |
Options accepted by {@link CalendarPlugin.modifyEvent}.
| Prop | Type | Description | Since |
|---|---|---|---|
filter |
EventFilter |
Fields identifying the event to change. | 1.0.0 |
newEvent |
Partial<CreateEventOptions> |
New values to apply. Only the fields present are changed. | 1.0.0 |
Fields used to locate the event to change in {@link CalendarPlugin.modifyEvent}. Set fields must all match.
| Prop | Type | Description | Since |
|---|---|---|---|
title |
string |
Title substring to match (case-insensitive). | 1.0.0 |
location |
string |
Location substring to match (case-insensitive). | 1.0.0 |
notes |
string |
Notes substring to match (case-insensitive). | 1.0.0 |
startDate |
number |
Start of the date range as epoch milliseconds. | 1.0.0 |
endDate |
number |
End of the date range as epoch milliseconds. | 1.0.0 |
calendarName |
string |
Restrict the match to the calendar with this name. | 1.0.0 |
Result of {@link CalendarPlugin.findEvents}.
| Prop | Type | Description | Since |
|---|---|---|---|
events |
CalendarEvent[] |
The events matching the search. | 1.0.0 |
A calendar event.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Platform-assigned event id. | 1.0.0 |
title |
string |
The event title. | 1.0.0 |
location |
string |
The event location. | 1.0.0 |
notes |
string |
Free-form event notes. | 1.0.0 |
startDate |
number |
Event start as epoch milliseconds. | 1.0.0 |
endDate |
number |
Event end as epoch milliseconds. | 1.0.0 |
isAllDay |
boolean |
Whether the event lasts all day. | 1.0.0 |
calendarId |
string |
Id of the calendar containing the event. | 1.0.0 |
calendarName |
string |
Name of the calendar containing the event. | 1.0.0 |
attendees |
EventAttendee[] |
The event's attendees. Absent when the event has none. | 1.0.0 |
An attendee of a {@link CalendarEvent}.
| Prop | Type | Description | Since |
|---|---|---|---|
name |
string |
The attendee's display name. | 1.0.0 |
email |
string |
The attendee's email address. | 1.0.0 |
status |
'unknown' | 'pending' | 'accepted' | 'declined' | 'tentative' | 'delegated' | 'completed' | 'in-process' |
The attendee's participation status. | 1.0.0 |
Options accepted by {@link CalendarPlugin.findEvents}.
| Prop | Type | Description | Since |
|---|---|---|---|
title |
string |
Title substring to match (case-insensitive). | 1.0.0 |
location |
string |
Location substring to match (case-insensitive). | 1.0.0 |
notes |
string |
Notes substring to match (case-insensitive). | 1.0.0 |
startDate |
number |
Start of the search range as epoch milliseconds. Defaults to the current time minus six months. | 1.0.0 |
endDate |
number |
End of the search range as epoch milliseconds. Defaults to the current time plus two years. | 1.0.0 |
calendarName |
string |
Restrict the search to the calendar with this name. | 1.0.0 |
Options accepted by {@link CalendarPlugin.deleteEvent}.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Id of the event to delete. When set, the filter fields are ignored. | 1.0.0 |
fromDate |
number |
Only with id, for a recurring event: keeps occurrences before this date (epoch milliseconds) and removes the rest of the series. |
1.0.0 |
title |
string |
Title substring to match (case-insensitive). | 1.0.0 |
location |
string |
Location substring to match (case-insensitive). | 1.0.0 |
notes |
string |
Notes substring to match (case-insensitive). | 1.0.0 |
startDate |
number |
Start of the date range as epoch milliseconds. | 1.0.0 |
endDate |
number |
End of the date range as epoch milliseconds. | 1.0.0 |
calendarName |
string |
Restrict the match to the calendar with this name. | 1.0.0 |
Result of {@link CalendarPlugin.listCalendars}.
| Prop | Type | Description | Since |
|---|---|---|---|
calendars |
DeviceCalendar[] |
The calendars on the device. | 1.0.0 |
A calendar available on the device.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Platform-assigned calendar id. | 1.0.0 |
name |
string |
The calendar name. | 1.0.0 |
displayName |
string |
Name shown to the user, when the platform distinguishes it from name. |
1.0.0 |
isPrimary |
boolean |
Whether this is the default calendar for new events. | 1.0.0 |
Result of {@link CalendarPlugin.createCalendar}.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
The created calendar's id. | 1.0.0 |
Options accepted by {@link CalendarPlugin.createCalendar}.
| Prop | Type | Description | Since |
|---|---|---|---|
name |
string |
The calendar name. | 1.0.0 |
color |
string |
Calendar color as a #RRGGBB hex string. The platform picks one when omitted. |
1.0.0 |
Options accepted by {@link CalendarPlugin.deleteCalendar}.
| Prop | Type | Description | Since |
|---|---|---|---|
name |
string |
Name of the calendar to delete. | 1.0.0 |
Options accepted by {@link CalendarPlugin.openCalendar}.
| Prop | Type | Description | Since |
|---|---|---|---|
date |
number |
Date to show, as epoch milliseconds. Today when omitted. | 1.0.0 |
'prompt' | 'prompt-with-rationale' | 'granted' | 'denied'
The individually requestable calendar permissions.
'readCalendar' | 'writeCalendar'
How often a recurring event repeats.
'daily' | 'weekly' | 'monthly' | 'yearly'
Make all properties in T optional
{
[P in keyof T]?: T[P];
}