@ebarooni/capacitor-calendar

The Capacitor Calendar Plugin enables full calendar functionality on iOS and Android, with added reminder support for iOS devices.

https://capacitor-calendar.pages.dev

Table of Contents

• Install
• Support Range
• Demo
• MVP
• Permissions
• API

Install

npm install @ebarooni/capacitor-calendar
npx cap sync

Support Range

Platform	range
iOS	≥ 13
Android	≥ 7 (SDK 24 or Nougat)

Demo (click for details)

iOS 17	Android 14

On iOS, readCalendar permission is not needed when you a

re creating an event using the native prompt. The video is just for showing the functionality, otherwise the createEventWithPrompt method works without the readCalendar authorization.

MVP

• ✅ Choose calendars with prompt (only supported on iOS)
• ✅ Get list of available calendars
• ✅ Get default calendar
• ✅ Create calendar events without native prompts
• ✅️ Create reminders (only supported on iOS)
• ⌛️ Find calendar events
• ⌛️ Delete calendar events

Permissions

To be able to use the plugin, you will need to add the required permissions to your app. The required platform-specific permissions can be found below:

• iOS
• Android

API

• checkPermission(...)
• checkAllPermissions()
• requestPermission(...)
• requestAllPermissions()
• createEventWithPrompt()
• selectCalendarsWithPrompt(...)
• listCalendars()
• getDefaultCalendar()
• createEvent(...)
• getDefaultRemindersList()
• getRemindersLists()
• createReminder(...)
• 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; }>

---

checkAllPermissions()

checkAllPermissions() => Promise<PluginPermissionsMap>

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

Returns: Promise<PluginPermissionsMap>

---

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

---

requestAllPermissions()

requestAllPermissions() => Promise<PluginPermissionsMap>

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

Returns: Promise<PluginPermissionsMap>

---

createEventWithPrompt()

createEventWithPrompt() => Promise<{ eventCreated: boolean; }>

Creates an event in the calendar by using the native calendar. On iOS opens a native sheet and on Android opens an intent. This method does not need any read or write authorization from the user on iOS. However, the entries in the Info.plist file are still needed. On Android, the user has to authorize for read access.

Returns: Promise<{ eventCreated: boolean; }>

---

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

---

listCalendars()

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

Retrieves a list of calendars available on the device.

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

---

getDefaultCalendar()

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

Retrieves the default calendar set on the device.

Returns: Promise<{ result: Calendar; }>

---

createEvent(...)

createEvent(options: { title: string; calendarId?: string; location?: string; startDate?: Date; endDate?: Date; isAllDay?: boolean; }) => Promise<{ eventCreated: boolean; }>

Creates an event with the provided options.

Param	Type	Description
options	{ title: string; calendarId?: string; location?: string; startDate?: Date; endDate?: Date; isAllDay?: boolean; }	- Options for creating the event.

Returns: Promise<{ eventCreated: boolean; }>

---

getDefaultRemindersList()

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

Retrieves the default reminders list set on the device.

Returns: Promise<{ result: RemindersList; }>

---

getRemindersLists()

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

Retrieves all available reminders lists on the device.

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

---

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<{ reminderCreated: boolean; }>

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<{ reminderCreated: boolean; }>

---

Interfaces

PluginPermissionsMap

Calendar

Represents a calendar object with an ID and title.

Prop	Type
id	string
title	string

Date

Enables basic storage and retrieval of dates and times.

Method	Signature	Description
toString	() => string	Returns a string representation of a date. The format of the string depends on the locale.
toDateString	() => string	Returns a date as a string value.
toTimeString	() => string	Returns a time as a string value.
toLocaleString	() => string	Returns a value as a string value appropriate to the host environment's current locale.
toLocaleDateString	() => string	Returns a date as a string value appropriate to the host environment's current locale.
toLocaleTimeString	() => string	Returns a time as a string value appropriate to the host environment's current locale.
valueOf	() => number	Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC.
getTime	() => number	Gets the time value in milliseconds.
getFullYear	() => number	Gets the year, using local time.
getUTCFullYear	() => number	Gets the year using Universal Coordinated Time (UTC).
getMonth	() => number	Gets the month, using local time.
getUTCMonth	() => number	Gets the month of a Date object using Universal Coordinated Time (UTC).
getDate	() => number	Gets the day-of-the-month, using local time.
getUTCDate	() => number	Gets the day-of-the-month, using Universal Coordinated Time (UTC).
getDay	() => number	Gets the day of the week, using local time.
getUTCDay	() => number	Gets the day of the week using Universal Coordinated Time (UTC).
getHours	() => number	Gets the hours in a date, using local time.
getUTCHours	() => number	Gets the hours value in a Date object using Universal Coordinated Time (UTC).
getMinutes	() => number	Gets the minutes of a Date object, using local time.
getUTCMinutes	() => number	Gets the minutes of a Date object using Universal Coordinated Time (UTC).
getSeconds	() => number	Gets the seconds of a Date object, using local time.
getUTCSeconds	() => number	Gets the seconds of a Date object using Universal Coordinated Time (UTC).
getMilliseconds	() => number	Gets the milliseconds of a Date, using local time.
getUTCMilliseconds	() => number	Gets the milliseconds of a Date object using Universal Coordinated Time (UTC).
getTimezoneOffset	() => number	Gets the difference in minutes between the time on the local computer and Universal Coordinated Time (UTC).
setTime	(time: number) => number	Sets the date and time value in the Date object.
setMilliseconds	(ms: number) => number	Sets the milliseconds value in the Date object using local time.
setUTCMilliseconds	(ms: number) => number	Sets the milliseconds value in the Date object using Universal Coordinated Time (UTC).
setSeconds	(sec: number, ms?: number | undefined) => number	Sets the seconds value in the Date object using local time.
setUTCSeconds	(sec: number, ms?: number | undefined) => number	Sets the seconds value in the Date object using Universal Coordinated Time (UTC).
setMinutes	(min: number, sec?: number | undefined, ms?: number | undefined) => number	Sets the minutes value in the Date object using local time.
setUTCMinutes	(min: number, sec?: number | undefined, ms?: number | undefined) => number	Sets the minutes value in the Date object using Universal Coordinated Time (UTC).
setHours	(hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number	Sets the hour value in the Date object using local time.
setUTCHours	(hours: number, min?: number | undefined, sec?: number | undefined, ms?: number | undefined) => number	Sets the hours value in the Date object using Universal Coordinated Time (UTC).
setDate	(date: number) => number	Sets the numeric day-of-the-month value of the Date object using local time.
setUTCDate	(date: number) => number	Sets the numeric day of the month in the Date object using Universal Coordinated Time (UTC).
setMonth	(month: number, date?: number | undefined) => number	Sets the month value in the Date object using local time.
setUTCMonth	(month: number, date?: number | undefined) => number	Sets the month value in the Date object using Universal Coordinated Time (UTC).
setFullYear	(year: number, month?: number | undefined, date?: number | undefined) => number	Sets the year of the Date object using local time.
setUTCFullYear	(year: number, month?: number | undefined, date?: number | undefined) => number	Sets the year value in the Date object using Universal Coordinated Time (UTC).
toUTCString	() => string	Returns a date converted to a string using Universal Coordinated Time (UTC).
toISOString	() => string	Returns a date as a string value in ISO format.
toJSON	(key?: any) => string	Used by the JSON.stringify method to enable the transformation of an object's data for JavaScript Object Notation (JSON) serialization.

RemindersList

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.

Type Aliases

PermissionState

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

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.

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
DAILY
WEEKLY
MONTHLY
YEARLY