A capacitor plugin for managing calendar events on iOS and Android, with reminder support on iOS.

Table of Contents

• Installation
• Demo
• Setup
• Documentation
• API
• Changelog
• Contributing
• License

Installation

npm install @ebarooni/capacitor-calendar
npx cap sync

Demo

iOS 17	Android 14

Setup

• iOS
• Android

📚 Documentation

For comprehensive explanations, usage examples, and additional information, please refer to the following resources:

• Online Documentation
• Type Definitions and Examples

📋 API

• checkPermission(...)
• checkAllPermissions()
• requestPermission(...)
• requestAllPermissions()
• createEventWithPrompt(...)
• selectCalendarsWithPrompt(...)
• listCalendars()
• getDefaultCalendar()
• createEvent(...)
• getDefaultRemindersList()
• getRemindersLists()
• createReminder(...)
• openCalendar(...)
• openReminders()
• listEventsInRange(...)
• deleteEventsById(...)
• createCalendar(...)
• deleteCalendar(...)
• getRemindersFromLists(...)
• deleteRemindersById(...)
• requestWriteOnlyCalendarAccess()
• requestReadOnlyCalendarAccess()
• requestFullCalendarAccess()
• requestFullRemindersAccess()
• modifyEventWithPrompt(...)
• modifyEvent(...)
• fetchAllCalendarSources()
• fetchAllRemindersSources()
• modifyReminder(...)
• Interfaces
• Type Aliases
• Enums

checkPermission(...)

checkPermission(options: { alias: PluginPermission; }) => Promise<{ result: PermissionState; }>

Checks the current authorization status of a specific permission.

Param	Type	Description
options	{ alias: PluginPermission; }	An object with the name of the permission

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

---

checkAllPermissions()

checkAllPermissions() => Promise<PluginPermissionsMap>

Checks the current authorization status of all the required permissions for the plugin.

Returns: Promise<PluginPermissionsMap>

Since: 0.1.0

---

requestPermission(...)

requestPermission(options: { alias: PluginPermission; }) => Promise<{ result: PermissionState; }>

Requests authorization to a specific permission, if not already granted. If the permission is already granted, it will directly return the status.

Param	Type	Description
options	{ alias: PluginPermission; }	An object with the name of the permission

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

---

requestAllPermissions()

requestAllPermissions() => Promise<PluginPermissionsMap>

Requests authorization to all the required permissions for the plugin, if they have not already been granted.

Returns: Promise<PluginPermissionsMap>

Since: 0.1.0

---

createEventWithPrompt(...)

createEventWithPrompt(options: { title: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; eventIdOptional?: boolean; }) => Promise<{ result: string[]; }>

Creates an event in the calendar by using the native calendar. On iOS opens a native sheet and on Android opens an intent.

Param	Type	Description
options	{ title: string; calendarId?: string; location?: string; startDate?: number; endDate?: number; isAllDay?: boolean; alertOffsetInMinutes?: number | number[]; url?: string; notes?: string; eventIdOptional?: boolean; }	Options for creating the event.

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

Since: 0.1.0

---

selectCalendarsWithPrompt(...)

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

listCalendars() => Promise<{ result: Calendar[]; }>

Retrieves a list of calendars available on the device.

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

---

getDefaultCalendar()

getDefaultCalendar() => Promise<{ result: Calendar | null; }>

Retrieves the default calendar set on the device.

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

Since: 0.3.0

---

createEvent(...)

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

getDefaultRemindersList() => Promise<{ result: RemindersList; }>

Retrieves the default reminders list set on the device.

Returns: Promise<{ result: Calendar; }>

---

getRemindersLists()

getRemindersLists() => Promise<{ result: RemindersList[]; }>

Retrieves all available reminders lists on the device.

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

---

createReminder(...)

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

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

openReminders() => Promise<void>

Opens the reminders app. Since the user leaves your app, use this method with caution.

---

listEventsInRange(...)

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

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

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

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

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

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

---

requestWriteOnlyCalendarAccess()

requestWriteOnlyCalendarAccess() => Promise<{ result: PermissionState; }>

Requests write access for the calendar. If its already granted, it will directly return the state.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

---

requestReadOnlyCalendarAccess()

requestReadOnlyCalendarAccess() => Promise<{ result: PermissionState; }>

Requests read access for the calendar. If its already granted, it will directly return the state.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

---

requestFullCalendarAccess()

requestFullCalendarAccess() => Promise<{ result: PermissionState; }>

Requests read and write access for the calendar. If its already granted, it will directly return the state.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

---

requestFullRemindersAccess()

requestFullRemindersAccess() => Promise<{ result: PermissionState; }>

Requests read and write access for the reminders. If its already granted, it will directly return the state.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

---

modifyEventWithPrompt(...)

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

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

fetchAllCalendarSources() => Promise<{ result: CalendarSource[]; }>

Retrieves a list of calendar sources.

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

Since: 6.6.0

---

fetchAllRemindersSources()

fetchAllRemindersSources() => Promise<{ result: CalendarSource[]; }>

Retrieves a list of reminders sources.

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

Since: 6.6.0

---

modifyReminder(...)

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

---

Interfaces

Calendar

Represents a calendar object.

Prop	Type
id	string
title	string
color	string
isImmutable	boolean
allowsContentModifications	boolean
type	CalendarType
isSubscribed	boolean
source	CalendarSource

CalendarSource

Represents the account a calendar belongs to

Prop	Type
type	CalendarSourceType
id	string
title	string

ReminderRecurrenceRule

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.

CalendarEvent

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

Reminder

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[]

Type Aliases

PermissionState

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

PluginPermissionsMap

Record<string, PermissionState>

Record

Construct a type with a set of properties K of type T

{ [P in K]: T; }

RemindersList

Calendar

Enums

PluginPermission

Members	Value	Description
READ_CALENDAR	"readCalendar"	Represents the permission state for reading calendar.
WRITE_CALENDAR	"writeCalendar"	Represents the permission state for writing calendar.
READ_REMINDERS	"readReminders"	Represents the permission state for reading reminders.
WRITE_REMINDERS	"writeReminders"	Represents the permission state for writing reminders.

CalendarType

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.

CalendarSourceType

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.

CalendarChooserDisplayStyle

Members	Description
ALL_CALENDARS	Display all calendars available for selection.
WRITABLE_CALENDARS_ONLY	Display only writable calendars available for selection.

CalendarChooserSelectionStyle

Members	Description
SINGLE	Allows only a single selection in the calendar chooser.
MULTIPLE	Allows multiple selections in the calendar chooser.

ReminderRecurrenceFrequency

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

EventSpan

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.

Changelog

See CHANGELOG.md

Contributing

See CONTRIBUTING.md

License

See LICENSE.txt