/ebarooni-capacitor-calendar

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

Primary LanguageTypeScriptMIT LicenseMIT

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

https://capacitor-calendar.pages.dev

Deployment Targets

Table of Contents

Install

npm install @ebarooni/capacitor-calendar
npx cap sync

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.

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:

💙 Contributions

Warning

Thank you for your interest in contributing to the project! At the moment, the focus is on reaching the first major release. Until then, the contributions will not be accepted. This approach allows to set a solid foundation and maintain consistency throughout the development process.

Community input is highly valued, and you are encouraged to engage with the project by providing feedback and suggestions. Feel free to open issues for bugs you've discovered or enhancements you'd like to see.

Stay tuned for updates. Looking forward to collaborating with you in the future once contributions are opened up!

API

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<{ 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.

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

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?: number; endDate?: number; isAllDay?: boolean; }) => 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; } - Options for creating the event.

Returns: Promise<{ result: string; }>

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<{ 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

Interfaces

PluginPermissionsMap

Calendar

Represents a calendar object.

Prop Type
id string
title string

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.

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 string
eventEndTimezone string
duration string
isAllDay boolean
calendarId string

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