@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]; }