@capacitor/calendar

Create, find, modify and remove events in the device calendar.

Install

To use npm

npm install @capacitor/calendar

To use yarn

yarn add @capacitor/calendar

Sync native files

npx cap sync

iOS

Add 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 / requestWriteOnlyAccessToEvents on iOS 17+), never the deprecated requestAccess(to:). writeCalendar is satisfied by write-only access ("Add Events Only"); readCalendar requires full access.
• createEventInteractively presents the system event editor, which on iOS 17+ needs no calendar permission at all.
• EventKit stores dates at second granularity, so startDate/endDate read back with milliseconds truncated. Android keeps exact milliseconds.

Android

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:

• createEventInteractively opens 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.url is ignored: the platform's event model has no URL field.

Errors

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 |

API

• checkPermissions()
• requestPermissions(...)
• createEvent(...)
• createEventInteractively(...)
• modifyEvent(...)
• findEvents(...)
• deleteEvent(...)
• listCalendars()
• createCalendar(...)
• deleteCalendar(...)
• openCalendar(...)
• Interfaces
• Type Aliases

checkPermissions()

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(...)

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(...)

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(...)

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(...)

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(...)

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(...)

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()

listCalendars() => Promise<ListCalendarsResult>

Returns the calendars available on the device.

Requires read permission.

Returns: Promise<ListCalendarsResult>

Since: 1.0.0

createCalendar(...)

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(...)

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(...)

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

Interfaces

CalendarPermissionStatus

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 |

RequestPermissionsOptions

Options accepted by {@link CalendarPlugin.requestPermissions}.

| Prop | Type | Description | Since | | ----------------- | ------------------------------------- | ------------------------------------------------------------ | ----- | | permissions | CalendarPermissionType[] | The permissions to request. Both are requested when omitted. | 1.0.0 |

CreateEventResult

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 |

CreateEventOptions

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 |

EventRecurrence

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 |

ModifyEventOptions

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 |

EventFilter

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 |

FindEventsResult

Result of {@link CalendarPlugin.findEvents}.

| Prop | Type | Description | Since | | ------------ | ---------------------------- | ------------------------------- | ----- | | events | CalendarEvent[] | The events matching the search. | 1.0.0 |

CalendarEvent

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 |

EventAttendee

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 |

FindEventsOptions

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 |

DeleteEventOptions

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 |

ListCalendarsResult

Result of {@link CalendarPlugin.listCalendars}.

| Prop | Type | Description | Since | | --------------- | ----------------------------- | ---------------------------- | ----- | | calendars | DeviceCalendar[] | The calendars on the device. | 1.0.0 |

DeviceCalendar

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 |

CreateCalendarResult

Result of {@link CalendarPlugin.createCalendar}.

| Prop | Type | Description | Since | | -------- | ------------------- | -------------------------- | ----- | | id | string | The created calendar's id. | 1.0.0 |

CreateCalendarOptions

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 |

DeleteCalendarOptions

Options accepted by {@link CalendarPlugin.deleteCalendar}.

| Prop | Type | Description | Since | | ---------- | ------------------- | ------------------------------- | ----- | | name | string | Name of the calendar to delete. | 1.0.0 |

OpenCalendarOptions

Options accepted by {@link CalendarPlugin.openCalendar}.

| Prop | Type | Description | Since | | ---------- | ------------------- | -------------------------------------------------------- | ----- | | date | number | Date to show, as epoch milliseconds. Today when omitted. | 1.0.0 |

Type Aliases

PermissionState

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

CalendarPermissionType

The individually requestable calendar permissions.

'readCalendar' | 'writeCalendar'

RecurrenceFrequency

How often a recurring event repeats.

'daily' | 'weekly' | 'monthly' | 'yearly'

Partial

Make all properties in T optional

{ [P in keyof T]?: T[P]; }