# @ebarooni/capacitor-calendar

![capacitor-calendar-logo](assets/images/text-logo.png) Full-featured Capacitor plugin for native calendar and reminders access. Manage permissions, create, modify, and delete events and reminders programmatically or via the native UI, query events within a given time period, and list all available calendars. ## Core Features - ✅ **Events** – Create, update, delete, and list events in a date range - ✅ **Native Prompts** – Built-in system dialogs for creating, editing, and deleting events - ✅ **Permissions** – Granular control (full access, write-only, read-only) - ✅ **Calendars** – List calendars, get default, create, modify, and delete custom calendars - ✅ **Open Calendar App** – Launch the native Calendar app directly - 📅 **Reminders** – Full create, read, update, delete support _(iOS only)_ - 🔍 **Advanced iOS Features** – Calendar sources, calendar selection prompts, default reminders list ## Supported Platforms - **iOS** — Full support (including Reminders and advanced features) - **Android** — Strong support for all core calendar features - **Web** — Not supported (Capacitor stub only - calls will fail) ## Why this plugin? - **Original and established.** Available since Capacitor 5, this plugin has been around longer than the alternatives and has matured over time. - **Actively maintained by the original author.** Updates, bug fixes, and new features are driven by someone who is deeply familiar with the codebase and committed to keeping it healthy. - **Fast support.** Questions, bug reports, and integration help are handled promptly. - **Reduced vendor risk.** Relying on a single plugin provider for all your needs is a liability. Choosing specialized, independent maintainers keeps your stack resilient. ## Table of Contents - [Installation](#installation) - [Demo](#demo) - [Setup](#setup) - [Quick Start](#quick-start) - [Usage Examples](#usage-examples) - [Documentation](#documentation) - [Changelog](#changelog) - [API](#api) - [Contributing](#contributing) - [License](#license) ## Installation ```bash npm install @ebarooni/capacitor-calendar npx cap sync ``` ## Demo | iOS 26 | Android 16 | | :-----------------------------: | :---------------------------------: | | ![](./assets/demo/ios-demo.gif) | ![](./assets/demo/android-demo.gif) | ## Setup This plugin works with native calendar APIs, so you'll need to configure permissions on each platform before requesting access at runtime. ### Android Add these permissions to `android/app/src/main/AndroidManifest.xml`: ```xml ``` Don't forget to request the matching runtime permissions before reading from or writing to the calendar. ### iOS Add the appropriate usage description keys to `ios/App/App/Info.plist`. Starting with iOS 17, Apple requires separate keys for write-only and full calendar access. ```xml NSCalendarsUsageDescription This app needs access to your calendar. NSCalendarsWriteOnlyAccessUsageDescription This app needs permission to create calendar events. NSCalendarsFullAccessUsageDescription This app needs permission to read and manage your calendar events. NSRemindersUsageDescription This app needs access to your reminders. NSRemindersFullAccessUsageDescription This app needs permission to read and manage your reminders. ``` > [!IMPORTANT] > Only include the keys your app actually needs. If you're only creating events, you can safely omit the full access and reminders entries. ### Official References - **iOS:** [Migrating to the Latest Calendar Access Levels](https://developer.apple.com/documentation/technotes/tn3152-migrating-to-the-latest-calendar-access-levels) - **Android:** [Calendar Provider User Permissions](https://developer.android.com/identity/providers/calendar-provider#manifest) ## Quick Start Here's a simple example to get you up and running quickly: ```typescript import { CapacitorCalendar } from '@ebarooni/capacitor-calendar'; const { result } = await CapacitorCalendar.requestFullCalendarAccess(); if (result !== 'granted') { throw new Error('Calendar permission denied'); } // Create an event starting in 1 hour, lasting 1 hour const startDate = Date.now() + 60 * 60 * 1000; const endDate = startDate + 60 * 60 * 1000; const { id } = await CapacitorCalendar.createEvent({ title: 'Product review', location: 'Office', startDate, endDate, description: 'Created with @ebarooni/capacitor-calendar', }); console.log('Event created with ID:', id); ``` > [!NOTE] > Dates are expected as Unix timestamps in milliseconds. ## Usage Examples ### Open the native event editor Use the system calendar UI to let users create or edit events: ```typescript await CapacitorCalendar.createEventWithPrompt({ title: 'Planning session', location: 'Office', startDate: Date.now() + 24 * 60 * 60 * 1000, endDate: Date.now() + 25 * 60 * 60 * 1000, }); ``` > [!NOTE] > On Android, this method always returns null. If you need the event ID, call `listEventsInRange(...)` afterward. ### List upcoming events ```typescript const now = Date.now(); const oneWeekLater = now + 7 * 24 * 60 * 60 * 1000; const { result: events } = await CapacitorCalendar.listEventsInRange({ from: now, to: oneWeekLater, }); console.log('Upcoming events:', events); ``` ### Working with Calendars ```typescript // Get all calendars and default calendar const { result: calendars } = await CapacitorCalendar.listCalendars(); const { result: defaultCalendar } = await CapacitorCalendar.getDefaultCalendar(); // Use default or fall back to first calendar const targetCalendarId = defaultCalendar?.id ?? calendars[0]?.id; ``` > [!NOTE] > On iOS you can also use `selectCalendarsWithPrompt()` to let the user pick calendars via the native interface. ### Create a Reminder (iOS only) ```typescript const { result } = await CapacitorCalendar.requestFullRemindersAccess(); if (result === 'granted') { await CapacitorCalendar.createReminder({ title: 'Send launch notes', dueDate: Date.now() + 2 * 24 * 60 * 60 * 1000, notes: 'Created with @ebarooni/capacitor-calendar', }); } ``` ## Documentation The full documentation is generated from TypeScript definitions and is available online: - **[Complete Documentation](https://ebarooni.github.io/capacitor-calendar/)** — Guides, examples, and full API reference (recommended) - **[Source Definitions](src/definitions.ts)** — The TypeScript source used to generate the docs ## Changelog See [CHANGELOG.md](CHANGELOG.md) for the latest updates and release history. ## API * [`checkPermission(...)`](#checkpermission) * [`checkAllPermissions()`](#checkallpermissions) * [`requestPermission(...)`](#requestpermission) * [`requestAllPermissions()`](#requestallpermissions) * [`requestWriteOnlyCalendarAccess()`](#requestwriteonlycalendaraccess) * [`requestReadOnlyCalendarAccess()`](#requestreadonlycalendaraccess) * [`requestFullCalendarAccess()`](#requestfullcalendaraccess) * [`requestFullRemindersAccess()`](#requestfullremindersaccess) * [`createEventWithPrompt(...)`](#createeventwithprompt) * [`modifyEventWithPrompt(...)`](#modifyeventwithprompt) * [`createEvent(...)`](#createevent) * [`modifyEvent(...)`](#modifyevent) * [`deleteEventsById(...)`](#deleteeventsbyid) * [`deleteEvent(...)`](#deleteevent) * [`deleteEventWithPrompt(...)`](#deleteeventwithprompt) * [`listEventsInRange(...)`](#listeventsinrange) * [`commit()`](#commit) * [`selectCalendarsWithPrompt(...)`](#selectcalendarswithprompt) * [`fetchAllCalendarSources()`](#fetchallcalendarsources) * [`listCalendars()`](#listcalendars) * [`getDefaultCalendar()`](#getdefaultcalendar) * [`openCalendar(...)`](#opencalendar) * [`createCalendar(...)`](#createcalendar) * [`deleteCalendar(...)`](#deletecalendar) * [`modifyCalendar(...)`](#modifycalendar) * [`createRemindersList(...)`](#createreminderslist) * [`deleteRemindersList(...)`](#deletereminderslist) * [`fetchAllRemindersSources()`](#fetchallreminderssources) * [`openReminders()`](#openreminders) * [`getDefaultRemindersList()`](#getdefaultreminderslist) * [`getRemindersLists()`](#getreminderslists) * [`createReminder(...)`](#createreminder) * [`deleteRemindersById(...)`](#deleteremindersbyid) * [`deleteReminder(...)`](#deletereminder) * [`modifyReminder(...)`](#modifyreminder) * [`getReminderById(...)`](#getreminderbyid) * [`getRemindersFromLists(...)`](#getremindersfromlists) * [`deleteReminderWithPrompt(...)`](#deletereminderwithprompt) * [`updateRemindersList(...)`](#updatereminderslist) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) * [Enums](#enums) ### checkPermission(...) ```typescript 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() ```typescript checkAllPermissions() => Promise<{ result: CheckAllPermissionsResult; }> ``` Retrieves the current state of all permissions. **Returns:** Promise<{ result: CheckAllPermissionsResult; }> **Since:** 0.1.0 **Platform:** Android, iOS -------------------- ### requestPermission(...) ```typescript 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() ```typescript requestAllPermissions() => Promise<{ result: RequestAllPermissionsResult; }> ``` Requests permission for all calendar and reminder permissions. **Returns:** Promise<{ result: CheckAllPermissionsResult; }> **Since:** 0.1.0 **Platform:** Android, iOS -------------------- ### requestWriteOnlyCalendarAccess() ```typescript requestWriteOnlyCalendarAccess() => Promise<{ result: PermissionState; }> ``` Requests write access to the calendar. **Returns:** Promise<{ result: PermissionState; }> **Since:** 5.4.0 **Platform:** Android, iOS -------------------- ### requestReadOnlyCalendarAccess() ```typescript requestReadOnlyCalendarAccess() => Promise<{ result: PermissionState; }> ``` Requests read access to the calendar. **Returns:** Promise<{ result: PermissionState; }> **Since:** 5.4.0 **Platform:** Android -------------------- ### requestFullCalendarAccess() ```typescript requestFullCalendarAccess() => Promise<{ result: PermissionState; }> ``` Requests read and write access to the calendar. **Returns:** Promise<{ result: PermissionState; }> **Since:** 5.4.0 **Platform:** Android, iOS -------------------- ### requestFullRemindersAccess() ```typescript requestFullRemindersAccess() => Promise<{ result: PermissionState; }> ``` Requests read and write access to the reminders. **Returns:** Promise<{ result: PermissionState; }> **Since:** 5.4.0 **Platform:** iOS -------------------- ### createEventWithPrompt(...) ```typescript 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(...) ```typescript 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(...) ```typescript 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(...) ```typescript modifyEvent(options: ModifyEventOptions) => Promise ``` Modifies an event. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | ModifyEventOptions | **Since:** 6.6.0 **Platform:** Android, iOS -------------------- ### deleteEventsById(...) ```typescript 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(...) ```typescript deleteEvent(options: DeleteEventOptions) => Promise ``` Deletes an event. | Param | Type | | ------------- | ----------------------------------------------------------------- | | **`options`** | DeleteEventOptions | **Since:** 7.1.0 **Platform:** Android, iOS -------------------- ### deleteEventWithPrompt(...) ```typescript 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(...) ```typescript 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() ```typescript commit() => Promise ``` Save the changes to the calendar. **Since:** 7.1.0 **Platform:** iOS -------------------- ### selectCalendarsWithPrompt(...) ```typescript 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() ```typescript fetchAllCalendarSources() => Promise<{ result: CalendarSource[]; }> ``` Retrieves a list of calendar sources. **Returns:** Promise<{ result: CalendarSource[]; }> **Since:** 6.6.0 **Platform:** iOS -------------------- ### listCalendars() ```typescript listCalendars() => Promise<{ result: Calendar[]; }> ``` Retrieves a list of all available calendars. **Returns:** Promise<{ result: Calendar[]; }> **Since:** 7.1.0 **Platform:** Android, iOS -------------------- ### getDefaultCalendar() ```typescript getDefaultCalendar() => Promise<{ result: Calendar | null; }> ``` Retrieves the default calendar. **Returns:** Promise<{ result: Calendar | null; }> **Since:** 0.3.0 **Platform:** Android, iOS -------------------- ### openCalendar(...) ```typescript openCalendar(options?: OpenCalendarOptions | undefined) => Promise ``` Opens the calendar app. | Param | Type | | ------------- | ------------------------------------------------------------------- | | **`options`** | OpenCalendarOptions | **Since:** 7.1.0 **Platform:** Android, iOS -------------------- ### createCalendar(...) ```typescript 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(...) ```typescript deleteCalendar(options: DeleteCalendarOptions) => Promise ``` Deletes a calendar by id. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | DeleteCalendarOptions | **Since:** 5.2.0 **Platform:** Android, iOS -------------------- ### modifyCalendar(...) ```typescript modifyCalendar(options: ModifyCalendarOptions) => Promise ``` Modifies a calendar with options. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | ModifyCalendarOptions | **Since:** 7.2.0 **Platform:** Android, iOS -------------------- ### createRemindersList(...) ```typescript createRemindersList(options: CreateRemindersListOptions) => Promise ``` Creates a new reminders list. | Param | Type | | ------------- | --------------------------------------------------------------------------------- | | **`options`** | CreateRemindersListOptions | **Returns:** Promise<CreateRemindersListResult> **Since:** 8.1.0 **Platform:** iOS -------------------- ### deleteRemindersList(...) ```typescript deleteRemindersList(options: DeleteRemindersListOptions) => Promise ``` Deletes a reminders list. | Param | Type | | ------------- | --------------------------------------------------------------------------------- | | **`options`** | DeleteRemindersListOptions | **Since:** 8.2.0 **Platform:** iOS -------------------- ### fetchAllRemindersSources() ```typescript fetchAllRemindersSources() => Promise<{ result: CalendarSource[]; }> ``` Retrieves a list of calendar sources. **Returns:** Promise<{ result: CalendarSource[]; }> **Since:** 6.6.0 **Platform:** iOS -------------------- ### openReminders() ```typescript openReminders() => Promise ``` Opens the reminders app. **Since:** 7.1.0 **Platform:** iOS -------------------- ### getDefaultRemindersList() ```typescript getDefaultRemindersList() => Promise<{ result: RemindersList | null; }> ``` Retrieves the default reminders list. **Returns:** Promise<{ result: Calendar | null; }> **Since:** 7.1.0 **Platform:** iOS -------------------- ### getRemindersLists() ```typescript getRemindersLists() => Promise<{ result: RemindersList[]; }> ``` Retrieves all available reminders lists. **Returns:** Promise<{ result: Calendar[]; }> **Since:** 7.1.0 **Platform:** iOS -------------------- ### createReminder(...) ```typescript createReminder(options: CreateReminderOptions) => Promise<{ id: string; }> ``` Creates a reminder. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | CreateReminderOptions | **Returns:** Promise<{ id: string; }> **Since:** 0.5.0 **Platform:** iOS -------------------- ### deleteRemindersById(...) ```typescript deleteRemindersById(options: DeleteRemindersByIdOptions) => Promise<{ result: DeleteRemindersByIdResult; }> ``` Deletes multiple reminders. | Param | Type | | ------------- | --------------------------------------------------------------------------------- | | **`options`** | DeleteRemindersByIdOptions | **Returns:** Promise<{ result: DeleteRemindersByIdResult; }> **Since:** 5.3.0 **Platform:** iOS -------------------- ### deleteReminder(...) ```typescript deleteReminder(options: DeleteReminderOptions) => Promise ``` Deletes a reminder. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | DeleteReminderOptions | **Since:** 7.1.0 **Platform:** iOS -------------------- ### modifyReminder(...) ```typescript modifyReminder(options: ModifyReminderOptions) => Promise ``` Modifies a reminder. | Param | Type | | ------------- | ----------------------------------------------------------------------- | | **`options`** | ModifyReminderOptions | **Since:** 6.7.0 **Platform:** iOS -------------------- ### getReminderById(...) ```typescript 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(...) ```typescript 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(...) ```typescript 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 -------------------- ### updateRemindersList(...) ```typescript updateRemindersList(options: UpdateRemindersListOptions) => Promise ``` Update a reminders list with options. | Param | Type | | ------------- | --------------------------------------------------------------------------------- | | **`options`** | UpdateRemindersListOptions | **Returns:** Promise<UpdateRemindersListResult> **Since:** 8.2.0 **Platform:** iOS -------------------- ### Interfaces #### CreateEventWithPromptOptions | Prop | Type | Description | Since | Platform | | ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------------ | | **`alerts`** | number[] | Alert times in minutes relative to the event start. Use negative numbers for reminders before the start, and positive numbers for reminders after the start. On iOS only 2 alerts are supported. | 7.1.0 | iOS | | **`availability`** | EventAvailability | | 7.1.0 | Android, iOS | | **`calendarId`** | string | | 0.1.0 | iOS | | **`description`** | string | | 7.1.0 | Android, iOS | | **`endDate`** | number | | 0.1.0 | Android, iOS | | **`invitees`** | string[] | An array of emails to invite. | 7.1.0 | Android | | **`isAllDay`** | boolean | | 0.1.0 | Android, iOS | | **`location`** | string | | 0.1.0 | Android, iOS | | **`recurrence`** | EventRecurrenceRule | Rules for creating a recurring event. | 7.3.0 | Android, iOS | | **`startDate`** | number | | 0.1.0 | Android, iOS | | **`title`** | string | | 0.1.0 | Android, iOS | | **`url`** | string | | 0.1.0 | iOS | #### EventRecurrenceRule | Prop | Type | Description | Default | Since | Platform | | -------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ----- | ------------ | | **`byMonth`** | number[] | Limits a yearly recurrence to specific months of the year. The values should be between 1 and 12. | | 7.1.0 | Android, iOS | | **`byMonthDay`** | number[] | Limits a monthly recurrence to specific days of the month. The values should be between 1 and 31. | | 7.1.0 | Android, iOS | | **`byWeekDay`** | number[] | Limits a weekly recurrence to specific weekdays. The values should be between 1 and 7. 1 means Monday and 7 means Sunday. | | 7.3.0 | Android, iOS | | **`count`** | number | The total number of occurrences. If set, the recurrence ends after this many occurrences. If `count` is provided, `end` is ignored. | | 7.3.0 | Android, iOS | | **`daysOfTheYear`** | number[] | Limits a yearly recurrence to specific days of the year (1 to 366). | | 7.3.0 | iOS | | **`end`** | number | End date of the recurrence series as a Unix timestamp in milliseconds. | | 7.1.0 | Android, iOS | | **`frequency`** | RecurrenceFrequency | How often the event repeats. | | 7.3.0 | Android, iOS | | **`interval`** | number | The interval between recurrences. Use in combination with `frequency`. For example, a weekly event with an interval of 2, results in the event occurring every 2 weeks. | 1 | 7.3.0 | Android, iOS | | **`weeksOfTheYear`** | number[] | Limits a yearly recurrence to specific ISO week numbers (1 to 53). | | 7.3.0 | iOS | #### ModifyEventWithPromptOptions | Prop | Type | Description | Since | Platform | | ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------------ | | **`alerts`** | number[] | Alert times in minutes relative to the event start. Use negative numbers for reminders before the start, and positive numbers for reminders after the start. On iOS only 2 alerts are supported. | 7.1.0 | iOS | | **`availability`** | EventAvailability | | 7.1.0 | Android, iOS | | **`calendarId`** | string | | 0.1.0 | iOS | | **`description`** | string | | 7.1.0 | Android, iOS | | **`endDate`** | number | | 0.1.0 | Android, iOS | | **`invitees`** | string[] | An array of emails to invite. | 7.1.0 | Android | | **`isAllDay`** | boolean | | 0.1.0 | Android, iOS | | **`location`** | string | | 0.1.0 | Android, iOS | | **`recurrence`** | EventRecurrenceRule | Rules for creating a recurring event. | 7.3.0 | Android, iOS | | **`startDate`** | number | | 0.1.0 | Android, iOS | | **`title`** | string | | 0.1.0 | Android, iOS | | **`url`** | string | | 0.1.0 | iOS | | **`id`** | string | The ID of the event to be modified. | 7.1.0 | Android, iOS | #### CreateEventOptions | Prop | Type | Description | Default | Since | Platform | | ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ----- | ------------ | | **`alerts`** | number[] | Alert times in minutes relative to the event start. Use negative numbers for alerts before the start, and positive numbers for alerts after the start. | | 7.1.0 | Android, iOS | | **`attendees`** | EventGuest[] | The event guests. | | 7.1.0 | Android | | **`availability`** | EventAvailability | | | 7.1.0 | Android, iOS | | **`calendarId`** | string | | | 0.1.0 | Android, iOS | | **`color`** | string | | | 7.1.0 | Android | | **`commit`** | boolean | Whether to save immediately (`true`) or batch changes for later (`false`). | true | 7.1.0 | iOS | | **`description`** | string | | | 7.1.0 | Android, iOS | | **`duration`** | string | Duration of the event in RFC2445 format. | | 7.1.0 | Android | | **`endDate`** | number | | | 0.1.0 | Android, iOS | | **`isAllDay`** | boolean | | | 0.1.0 | Android, iOS | | **`location`** | string | | | 0.1.0 | Android, iOS | | **`organizer`** | string | Email of the event organizer. | | 7.1.0 | Android | | **`recurrence`** | EventRecurrenceRule | Rules for creating a recurring event. | | 7.3.0 | Android, iOS | | **`startDate`** | number | | | 0.1.0 | Android, iOS | | **`title`** | string | | | 0.4.0 | Android, iOS | | **`url`** | string | | | 0.1.0 | iOS | #### EventGuest | Prop | Type | Since | | ----------- | ------------------- | ----- | | **`name`** | string | 7.1.0 | | **`email`** | string | 7.1.0 | #### ModifyEventOptions | Prop | Type | Description | Default | Since | Platform | | ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | ----- | ------------ | | **`alerts`** | number[] | Alert times in minutes relative to the event start. Use negative numbers for alerts before the start, and positive numbers for alerts after the start. | | 7.1.0 | Android, iOS | | **`attendees`** | EventGuest[] | The event guests. | | 7.1.0 | Android | | **`availability`** | EventAvailability | | | 7.1.0 | Android, iOS | | **`calendarId`** | string | | | 0.1.0 | Android, iOS | | **`color`** | string | | | 7.1.0 | Android | | **`description`** | string | | | 7.1.0 | Android, iOS | | **`duration`** | string | Duration of the event in RFC2445 format. | | 7.1.0 | Android | | **`endDate`** | number | | | 0.1.0 | Android, iOS | | **`id`** | string | The ID of the event to be modified. | | 7.1.0 | Android, iOS | | **`isAllDay`** | boolean | | | 0.1.0 | Android, iOS | | **`location`** | string | | | 0.1.0 | Android, iOS | | **`recurrence`** | EventRecurrenceRule | Rules for creating a recurring event. | | 7.3.0 | Android, iOS | | **`organizer`** | string | Email of the event organizer. | | 7.1.0 | Android | | **`span`** | EventSpan | The span of modifications. | EventSpan.THIS_EVENT | | iOS | | **`startDate`** | number | | | 0.1.0 | Android, iOS | | **`title`** | string | | | 0.4.0 | Android, iOS | | **`url`** | string | | | 0.1.0 | 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 | Description | 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[] | Alert times in minutes relative to the event start. | 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 | #### CreateRemindersListResult | Prop | Type | Description | Since | Platform | | -------- | ------------------- | ----------------------------------------------- | ----- | -------- | | **`id`** | string | Identifier of the newly created reminders list. | 8.1.0 | iOS | #### CreateRemindersListOptions | Prop | Type | Description | Default | Since | Platform | | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----- | -------- | | **`color`** | 'blue' \| 'brown' \| 'gray' \| 'green' \| 'indigo' \| 'orange' \| 'pink' \| 'purple' \| 'red' \| 'teal' \| 'yellow' | The color of the list. | 'blue' | 8.1.0 | iOS | | **`commit`** | boolean | Whether to save the list to the event store immediately. Pass `false` to batch multiple changes and commit them together using `CapacitorCalendar.commit()`, which is more efficient than committing each save individually. | true | 8.1.0 | iOS | | **`sourceId`** | string | The EKSource identifier (account) where the list should be created. If left undefined, iCloud will be used if available, otherwise falls back to local. | | 8.1.0 | iOS | | **`title`** | string | The title of the list. | | 8.1.0 | iOS | #### DeleteRemindersListOptions | Prop | Type | Description | Default | Since | Platform | | ------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- | -------- | | **`commit`** | boolean | Whether to save the deletion to the event store immediately. Pass `false` to batch multiple changes and commit them together using `CapacitorCalendar.commit()`, which is more efficient than committing each save individually. | true | 8.2.0 | iOS | | **`id`** | string | Identifier of the reminders list to delete. | | 8.2.0 | iOS | #### CreateReminderOptions | Prop | Type | Description | 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[] | Alert times in minutes relative to the reminder start. Use negative numbers for alerts before the start, and positive numbers for alerts after the start. | 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 | Description | 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[] | Alert times in minutes relative to the reminder start. Use negative numbers for alerts before the start, and positive numbers for alerts after the start. On iOS only 2 alerts are supported. | 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 | #### UpdateRemindersListResult | Prop | Type | Description | Since | Platform | | -------- | ------------------- | ----------------------------------------- | ----- | -------- | | **`id`** | string | Identifier of the updated reminders list. | 8.2.0 | iOS | #### UpdateRemindersListOptions | Prop | Type | Description | Default | Since | Platform | | ------------ | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | ----- | -------- | | **`color`** | 'blue' \| 'brown' \| 'gray' \| 'green' \| 'indigo' \| 'orange' \| 'pink' \| 'purple' \| 'red' \| 'teal' \| 'yellow' | The new color of the list. If omitted, the color is left unchanged. | | 8.1.0 | iOS | | **`commit`** | boolean | Whether to save the update to the event store immediately. Pass `false` to batch multiple changes and commit them together using `eventStore.commit()`, which is more efficient than committing each save individually. | true | 8.2.0 | iOS | | **`id`** | string | The identifier of the list to update. | | 8.2.0 | iOS | | **`title`** | string | The new title of the list. If omitted, the title is left unchanged. | | 8.2.0 | iOS | ### 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 #### RecurrenceFrequency 'daily' | 'weekly' | 'monthly' | 'yearly' #### 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 | ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ## License This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.