@ebarooni/capacitor-calendar

capacitor-calendar-logo
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:

Changelog

See CHANGELOG.md for the latest updates and release history.

[!NOTE]
Version 7.1.0 introduces breaking changes.

API

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

deleteEventsById(...)

deleteEventsById(options: DeleteEventsByIdOptions) => Promise<{ result: DeleteEventsByIdResult; }>

Deletes multiple events.

Param Type
options DeleteEventsByIdOptions

Returns: Promise<{ result: DeleteEventsByIdResult; }>

Since: 0.11.0

Platform: Android, iOS

deleteEvent(...)

deleteEvent(options: DeleteEventOptions) => Promise<void>

Deletes an event.

Param Type
options DeleteEventOptions

Since: 7.1.0

Platform: Android, iOS

deleteEventWithPrompt(...)

deleteEventWithPrompt(options: DeleteEventWithPromptOptions) => Promise<{ deleted: boolean; }>

Opens a dialog to delete an event.

Param Type
options DeleteEventWithPromptOptions

Returns: Promise<{ deleted: boolean; }>

Since: 7.1.0

Platform: Android, iOS

listEventsInRange(...)

listEventsInRange(options: ListEventsInRangeOptions) => Promise<{ result: CalendarEvent[]; }>

Retrieves the events within a date range.

Param Type
options ListEventsInRangeOptions

Returns: Promise<{ result: CalendarEvent[]; }>

Since: 0.10.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

modifyCalendar(...)

modifyCalendar(options: ModifyCalendarOptions) => Promise<void>

Modifies a calendar with options.

Param Type
options ModifyCalendarOptions

Since: 7.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: CreateReminderOptions) => Promise<{ id: string; }>

Creates a reminder.

Param Type
options CreateReminderOptions

Returns: Promise<{ id: string; }>

Since: 0.5.0

Platform: iOS

deleteRemindersById(...)

deleteRemindersById(options: DeleteRemindersByIdOptions) => Promise<{ result: DeleteRemindersByIdResult; }>

Deletes multiple reminders.

Param Type
options DeleteRemindersByIdOptions

Returns: Promise<{ result: DeleteRemindersByIdResult; }>

Since: 5.3.0

Platform: iOS

deleteReminder(...)

deleteReminder(options: DeleteReminderOptions) => Promise<void>

Deletes a reminder.

Param Type
options DeleteReminderOptions

Since: 7.1.0

Platform: iOS

modifyReminder(...)

modifyReminder(options: ModifyReminderOptions) => Promise<void>

Modifies a reminder.

Param Type
options ModifyReminderOptions

Since: 6.7.0

Platform: iOS

getReminderById(...)

getReminderById(options: GetReminderByIdOptions) => Promise<{ result: Reminder | null; }>

Retrieve a reminder by ID.

Param Type
options GetReminderByIdOptions

Returns: Promise<{ result: Reminder | null; }>

Since: 7.1.0

Platform: iOS

getRemindersFromLists(...)

getRemindersFromLists(options: GetRemindersFromListsOptions) => Promise<{ result: Reminder[]; }>

Retrieves reminders from multiple lists.

Param Type
options GetRemindersFromListsOptions

Returns: Promise<{ result: Reminder[]; }>

Since: 5.3.0

Platform: iOS

deleteReminderWithPrompt(...)

deleteReminderWithPrompt(options: DeleteReminderWithPromptOptions) => Promise<{ deleted: boolean; }>

Opens a dialog to delete a reminder.

Param Type
options DeleteReminderWithPromptOptions

Returns: Promise<{ deleted: boolean; }>

Since: 7.2.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

DeleteEventsByIdResult

Prop Type Since
deleted string[] 7.1.0
failed string[] 7.1.0

DeleteEventsByIdOptions

Prop Type Description Default Since Platform
ids string[] 7.1.0
span EventSpan The span of deletion. EventSpan.THIS_EVENT iOS

DeleteEventOptions

Prop Type Description Default Since Platform
id string 7.1.0
span EventSpan The span of deletion. EventSpan.THIS_EVENT iOS

DeleteEventWithPromptOptions

Prop Type Description Default Since Platform
id string 7.1.0
span EventSpan The span of deletion. EventSpan.THIS_EVENT iOS
title string Title of the dialog. 7.1.0 Android, iOS
message string Message of the dialog. 7.1.0 Android, iOS
confirmButtonText string Text to show on the confirm button. 'Delete' 7.1.0 Android, iOS
cancelButtonText string Text to show on the cancel button. 'Cancel' 7.1.0 Android, iOS

CalendarEvent

Prop Type Since Platform
id string 7.1.0 Android, iOS
title string 7.1.0 Android, iOS
calendarId string | null 7.1.0 Android, iOS
location string | null 7.1.0 Android, iOS
startDate number 7.1.0 Android, iOS
endDate number 7.1.0 Android, iOS
isAllDay boolean 7.1.0 Android, iOS
alerts number[] 7.1.0 Android, iOS
url string | null 7.1.0 iOS
description string | null 7.1.0 Android, iOS
availability EventAvailability | null 7.1.0 Android, iOS
organizer string | null 7.1.0 Android, iOS
color string | null 7.1.0 Android, iOS
duration string | null 7.1.0 Android
isDetached boolean | null 7.1.0 iOS
birthdayContactIdentifier string | null 7.1.0 iOS
status EventStatus | null 7.1.0 Android, iOS
creationDate number | null 7.1.0 iOS
lastModifiedDate number | null 7.1.0 iOS
attendees { email: string | null; name: string | null; role: AttendeeRole | null; status: AttendeeStatus | null; type: AttendeeType | null; }[] 7.1.0 Android, iOS
timezone string | null 7.1.0 Android, iOS

ListEventsInRangeOptions

Prop Type Description Since
from number The timestamp in milliseconds. 7.1.0
to number The timestamp in milliseconds. 7.1.0

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

ModifyCalendarOptions

Prop Type Since Platform
id string 7.2.0 Android, iOS
title string 7.2.0 Android, iOS
color string 7.2.0 Android, iOS

CreateReminderOptions

Prop Type Since
title string 7.1.0
listId string 7.1.0
priority number 7.1.0
isCompleted boolean 7.1.0
startDate number 7.1.0
dueDate number 7.1.0
completionDate number 7.1.0
notes string 7.1.0
url string 7.1.0
location string 7.1.0
recurrence RecurrenceRule 7.1.0
alerts number[] 7.1.0

RecurrenceRule

Prop Type Description Since
frequency RecurrenceFrequency 7.1.0
interval number How often it repeats (e.g. 1 for every occurrence, 2 for every second occurrence). 7.1.0
end number Timestamp of when the recurrence ends. 7.1.0

DeleteRemindersByIdResult

Prop Type Since
deleted string[] 7.1.0
failed string[] 7.1.0

DeleteRemindersByIdOptions

Prop Type Since
ids string[] 7.1.0

DeleteReminderOptions

Prop Type Since
id string 7.1.0

ModifyReminderOptions

Prop Type Since
id string 7.1.0
title string 7.1.0
listId string 7.1.0
priority number 7.1.0
isCompleted boolean 7.1.0
startDate number 7.1.0
dueDate number 7.1.0
completionDate number 7.1.0
notes string 7.1.0
url string 7.1.0
location string 7.1.0
recurrence RecurrenceRule 7.1.0
alerts number[] 7.1.0

Reminder

Prop Type Since
id string 7.1.0
title string | null 7.1.0
listId string | null 7.1.0
isCompleted boolean 7.1.0
priority number | null 7.1.0
notes string | null 7.1.0
location string | null 7.1.0
url string | null 7.1.0
startDate number | null 7.1.0
dueDate number | null 7.1.0
completionDate number | null 7.1.0
recurrence RecurrenceRule[] 7.1.0
alerts number[] 7.1.0

GetReminderByIdOptions

Prop Type Since
id string 7.1.0

GetRemindersFromListsOptions

Prop Type Since
listIds string[] 7.1.0

DeleteReminderWithPromptOptions

Prop Type Description Default Since
id string 7.2.0
title string Title of the dialog. 7.2.0
message string Message of the dialog. 7.2.0
confirmButtonText string Text to show on the confirm button. 'Delete' 7.2.0
cancelButtonText string Text to show on the cancel button. 'Cancel' 7.2.0

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

CheckAllPermissionsResult

EventEditAction

"canceled" | "saved" | "deleted"

RemindersList

Calendar

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

EventStatus

Members Value Since Platform
NONE "none" 7.1.0 iOS
CONFIRMED "confirmed" 7.1.0 Android, iOS
TENTATIVE "tentative" 7.1.0 Android, iOS
CANCELED "canceled" 7.1.0 Android, iOS

AttendeeRole

Members Value Since Platform
UNKNOWN "unknown" 7.1.0 Android, iOS
REQUIRED "required" 7.1.0 iOS
OPTIONAL "optional" 7.1.0 iOS
CHAIR "chair" 7.1.0 iOS
NON_PARTICIPANT "nonParticipant" 7.1.0 Android, iOS
ATTENDEE "attendee" 7.1.0 Android
ORGANIZER "organizer" 7.1.0 Android
PERFORMER "performer" 7.1.0 Android
SPEAKER "speaker" 7.1.0 Android

AttendeeStatus

Members Value Since Platform
NONE "none" 7.1.0 Android
ACCEPTED "accepted" 7.1.0 Android, iOS
DECLINED "declined" 7.1.0 Android, iOS
INVITED "invited" 7.1.0 Android
UNKNOWN "unknown" 7.1.0 iOS
PENDING "pending" 7.1.0 iOS
TENTATIVE "tentative" 7.1.0 Android, iOS
DELEGATED "delegated" 7.1.0 iOS
COMPLETED "completed" 7.1.0 iOS
IN_PROCESS "inProcess" 7.1.0 iOS

AttendeeType

Members Value Since Platform
UNKNOWN "unknown" 7.1.0 Android, iOS
PERSON "person" 7.1.0 iOS
ROOM "room" 7.1.0 iOS
RESOURCE "resource" 7.1.0 Android, iOS
GROUP "group" 7.1.0 iOS
REQUIRED "required" 7.1.0 Android
NONE "none" 7.1.0 Android
OPTIONAL "optional" 7.1.0 Android

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

RecurrenceFrequency

Members Since
DAILY 7.1.0
WEEKLY 7.1.0
MONTHLY 7.1.0
YEARLY 7.1.0

Contributing

See CONTRIBUTING.md for guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.

Settings

Member Visibility

On This Page

Table of ContentsInstallationDemoSetupDocumentationChangelogAPIContributingLicense