@ebarooni/capacitor-calendar

@ebarooni/capacitor-calendar connects your Capacitor app to the native calendar. On iOS and Android, create, edit, and list events, and manage calendars and permissions. iOS also supports reminders. On the web, the plugin builds a downloadable .ics file; it does not write to a device calendar.

Table of Contents

• Features and Platforms
• Demo
• Why this plugin?
• MCP Server
• Capacitor Compatibility
• Installation
• Setup
• Error codes
• Quick Start
• Usage Examples
• Documentation
• Changelog
• Breaking Changes
• API
• Contributing
• License

Features and Platforms

* On the web, createEvent and createEventWithPrompt return a downloadable .ics file. They do not write to a device calendar. See Create and download an event on the web.

Demo

iOS	Android

Web: Run the example app in a browser. Use Create event or Create event with prompt for .ics export. Unsupported actions are disabled.

Why this plugin?

• Established. Available since Capacitor 5, with years of real-world use behind it.
• Actively maintained. The original author still owns the codebase and ships fixes and features.
• Fast support. Questions and bug reports get quick answers.
• Lower vendor risk. Relying on one plugin author for everything is risky. Independent, focused maintainers keep your stack resilient.

MCP Server

@ebarooni/capacitor-calendar ships an official MCP server. It gives AI coding assistants accurate, grounded knowledge of the plugin.

docker run --rm -d --name capacitor-calendar-mcp -p 8080:8080 ghcr.io/ebarooni/capacitor-calendar-mcp:1.2.0

See mcp/README.md for client configuration and full details.

Capacitor Compatibility

Match the npm tag to your Capacitor major. The latest and latest-7 packages are intended to stay in feature parity.

Capacitor	npm tag	Version
8.x	latest
7.x	latest-7

Installation

Capacitor 8:

npm install @ebarooni/capacitor-calendar
# or: npm install @ebarooni/capacitor-calendar@latest
npx cap sync

Capacitor 7:

npm install @ebarooni/capacitor-calendar@latest-7
npx cap sync

Setup

This plugin works with native calendar APIs, so you need to configure permissions on each platform before you request access at runtime. After setup, see Quick Start to request permissions in code.

Android

Add these permissions to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.READ_CALENDAR" />
<uses-permission android:name="android.permission.WRITE_CALENDAR" />

Request the matching runtime permissions before you read from or write 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.

<key>NSCalendarsUsageDescription</key>
<string>This app needs access to your calendar.</string>

<key>NSCalendarsWriteOnlyAccessUsageDescription</key>
<string>This app needs permission to create calendar events.</string>

<key>NSCalendarsFullAccessUsageDescription</key>
<string>This app needs permission to read and manage your calendar events.</string>

<key>NSRemindersUsageDescription</key>
<string>This app needs access to your reminders.</string>

<key>NSRemindersFullAccessUsageDescription</key>
<string>This app needs permission to read and manage your reminders.</string>

[!IMPORTANT]
Only include the keys your app actually needs. If you only create events, you can omit the full access and reminders entries.

Official References

• iOS: Migrating to the Latest Calendar Access Levels
• Android: Calendar Provider User Permissions

Error codes

On Android and iOS, a rejected call can expose error.code (stable category) and error.message (exact cause). Compare codes with the exported CapacitorCalendarErrorCode enum. Not every reject has a code yet; later releases add more catalog cases.

Defined codes:

Android rejects a non-numeric or empty calendar or event id as InvalidArgument. iOS looks up the string in the system calendar store and may reject as NotFound when nothing matches.

IoError: Android and iOS map store failures such as failed create/delete ID retrieval and delete failures. Other calendar store errors that are not permission or launch failures also use this code. On iOS, EventKit store or system rejects use this code, including some authorization-related failures; Android permission-provider denials still use PermissionDenied (EB-CLDR-0020). On iOS, this code also covers the edit-prompt processFailed outcome.

NotSupported: Android maps a missing calendar activity handler (ActivityNotFoundException, for example openCalendar) to this code. iOS maps launch and URL failures (Failed to launch calendar app., reminders, Unable to open URL.).

On Android, calendar operations that fail with a permission error reject with PermissionDenied (EB-CLDR-0020). Permission check and request APIs still resolve "denied" on Android and iOS; they do not reject with 0020.

For Android and iOS wraps of system store, launch, and permission failures, the message starts with a fixed sentence. If the OS provides a different detail, it is appended in parentheses.

Quick Start

The sample below is for Android and iOS. For Web, see Create and download an event on the web.

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

Create and download an event on the web

On Web, createEvent and createEventWithPrompt build an .ics file. They do not write to a calendar store. Use autoDownloadIcsFile (defaults: false on createEvent, true on createEventWithPrompt) or downloadIcsFile. Permission APIs are unimplemented. For details, see MCP docs://web-behavior (mcp/README.md).

import { CapacitorCalendar } from '@ebarooni/capacitor-calendar';

const startDate = Date.now() + 60 * 60 * 1000;
const endDate = startDate + 60 * 60 * 1000;

const { ics } = await CapacitorCalendar.createEvent({
  title: 'Team standup',
  startDate,
  endDate,
  icsFileName: 'team-standup.ics',
  autoDownloadIcsFile: true,
});

Open the native event editor

Use the system calendar UI to let users create or edit events (on Web: confirm dialog + ICS):

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 for id. If you need the event ID, call listEventsInRange(...) afterward. On Web, cancel resolves with ics: null.

Modify or delete an event

The sample below is for Android and iOS. Use an id from createEvent or listEventsInRange:

await CapacitorCalendar.modifyEvent({
  id: eventId,
  title: 'Updated title',
});

await CapacitorCalendar.deleteEvent({
  id: eventId,
});

List events in a range

listEventsInRange returns events that overlap the given range, not only events that start or end inside it. Multi-day events that span the interval are included.

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

To list events on a single day, use that day's bounds:

const startOfDay = new Date();
startOfDay.setHours(0, 0, 0, 0);
const startOfNextDay = new Date(startOfDay);
startOfNextDay.setDate(startOfNextDay.getDate() + 1);

const { result: todaysEvents } = await CapacitorCalendar.listEventsInRange({
  from: startOfDay.getTime(),
  to: startOfNextDay.getTime(),
});

Working with Calendars

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

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 — Guides, examples, and full API reference (recommended)
• Source Definitions — The TypeScript source used to generate the docs

Changelog

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

Breaking Changes

See BREAKING.md for breaking changes and migration steps.

API

• checkPermission(...)
• checkAllPermissions()
• requestPermission(...)
• requestAllPermissions()
• requestWriteOnlyCalendarAccess()
• requestReadOnlyCalendarAccess()
• requestFullCalendarAccess()
• requestFullRemindersAccess()
• createEventWithPrompt(...)
• modifyEventWithPrompt(...)
• createEvent(...)
• modifyEvent(...)
• deleteEventsById(...)
• deleteEvent(...)
• deleteEventWithPrompt(...)
• listEventsInRange(...)
• commit()
• selectCalendarsWithPrompt(...)
• fetchAllCalendarSources()
• listCalendars()
• getDefaultCalendar(...)
• openCalendar(...)
• createCalendar(...)
• deleteCalendar(...)
• modifyCalendar(...)
• createRemindersList(...)
• deleteRemindersList(...)
• fetchAllRemindersSources()
• openReminders()
• getDefaultRemindersList()
• getRemindersLists()
• createReminder(...)
• deleteRemindersById(...)
• deleteReminder(...)
• modifyReminder(...)
• getReminderById(...)
• getRemindersFromLists(...)
• deleteReminderWithPrompt(...)
• updateRemindersList(...)
• Interfaces
• Type Aliases
• Enums

checkPermission(...)

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

Retrieves the current permission state for a given scope. On Android, readReminders and writeReminders resolve to "prompt".

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

Platform: Android, iOS

checkAllPermissions()

checkAllPermissions() => Promise<{ result: CheckAllPermissionsResult; }>

Retrieves the current state of all permissions. On Android, reminder keys always resolve to "prompt".

Returns: Promise<{ result: CheckAllPermissionsResult; }>

Since: 0.1.0

Platform: Android, iOS

requestPermission(...)

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

Requests permission for a given scope. On Android, readReminders and writeReminders reject with Invalid scope.

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

Platform: Android, iOS

requestAllPermissions()

requestAllPermissions() => Promise<{ result: RequestAllPermissionsResult; }>

Requests permission for all calendar and reminder permissions. On Android, only calendar permissions are requested; reminder keys stay "prompt".

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. Resolves with "granted" or "denied" (never "prompt"). A grant covers both readReminders and writeReminders.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: iOS

createEventWithPrompt(...)

createEventWithPrompt(options?: CreateEventWithPromptOptions | undefined) => Promise<CreateEventWithPromptResult>

Opens a calendar UI to create an event. On Android and iOS, opens the system editor. On Android, id is always null. On Web, shows a confirm dialog, then builds an .ics File when the user confirms. See MCP docs://web-behavior for Web details.

Returns: Promise<CreateEventWithPromptResult>

Since: 0.1.0

Platform: Android, iOS, Web

modifyEventWithPrompt(...)

modifyEventWithPrompt(options: ModifyEventWithPromptOptions) => Promise<{ result: EventEditAction | null; }>

Opens a system calendar interface to modify an event. On Android always returns null.

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

Since: 6.6.0

Platform: Android, iOS

createEvent(...)

createEvent(options: CreateEventOptions) => Promise<CreateEventResult>

Creates an event in the calendar. On Android and iOS, inserts into the system calendar and returns its id. On Web, builds an .ics File as ics (no calendar store). See MCP docs://web-behavior.

Returns: Promise<CreateEventResult>

Since: 0.4.0

Platform: Android, iOS, Web

modifyEvent(...)

modifyEvent(options: ModifyEventOptions) => Promise<void>

Modifies an event.

Since: 6.6.0

Platform: Android, iOS

deleteEventsById(...)

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

Deletes multiple events.

Returns: Promise<{ result: DeleteEventsByIdResult; }>

Since: 0.11.0

Platform: Android, iOS

deleteEvent(...)

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

Deletes an event.

Since: 7.1.0

Platform: Android, iOS

deleteEventWithPrompt(...)

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

Opens a dialog to delete an event.

Returns: Promise<{ deleted: boolean; }>

Since: 7.1.0

Platform: Android, iOS

listEventsInRange(...)

listEventsInRange(options: ListEventsInRangeOptions) => Promise<ListEventsInRangeResult>

Retrieves events that overlap a date range.

An event is included when its time interval intersects [from, to], including multi-day events that span the range without starting or ending inside it.

Returns: Promise<ListEventsInRangeResult>

Since: 0.10.0

Platform: Android, iOS

commit()

commit() => Promise<void>

Saves pending calendar changes.

Since: 7.1.0

Platform: iOS

selectCalendarsWithPrompt(...)

selectCalendarsWithPrompt(options?: SelectCalendarsWithPromptOptions | undefined) => Promise<SelectCalendarsWithPromptResult>

Opens a system interface to choose one or multiple calendars.

Calendar access is expected. Call requestFullCalendarAccess() first. Without authorization the chooser can look empty.

On confirm, result contains the calendars the user selected. On cancel, result is an empty array.

If a chooser is already presented, a new call is rejected; the in-flight call continues until the user confirms or cancels.

Returns: Promise<SelectCalendarsWithPromptResult>

Since: 0.2.0

Platform: iOS

fetchAllCalendarSources()

fetchAllCalendarSources() => Promise<FetchAllCalendarSourcesResult>

Retrieves a list of calendar sources.

Requires calendar access. Without authorization, result is typically an empty array. This method does not reject solely for missing permission.

Returns: Promise<FetchAllCalendarSourcesResult>

Since: 6.6.0

Platform: iOS

listCalendars()

listCalendars() => Promise<ListCalendarsResult>

Retrieves a list of all available calendars.

Requires calendar read access. On Android, missing permission typically rejects. On iOS, missing authorization typically returns an empty result.

Returns: Promise<ListCalendarsResult>

Since: 7.1.0

Platform: Android, iOS

getDefaultCalendar(...)

getDefaultCalendar(options?: GetDefaultCalendarOptions | undefined) => Promise<{ result: Calendar | null; }>

Retrieves the default calendar.

Requires calendar read access. On Android, missing permission typically rejects. On iOS, missing authorization typically yields result: null.

The system default is the primary calendar on Android and defaultCalendarForNewEvents on iOS. When neither exists and useFallbackCalendar is true, the first available calendar is returned. Otherwise the method returns null when there is no system default.

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

Since: 0.3.0

Platform: Android, iOS

openCalendar(...)

openCalendar(options?: OpenCalendarOptions | undefined) => Promise<void>

Opens the calendar app.

Since: 7.1.0

Platform: Android, iOS

createCalendar(...)

createCalendar(options: CreateCalendarOptions) => Promise<CreateCalendarResult>

Creates a calendar.

title is required. color is optional and defaults to #007AFF. On Android, accountName and ownerAccount are required at runtime.

Returns: Promise<CreateCalendarResult>

Since: 5.2.0

Platform: Android, iOS

deleteCalendar(...)

deleteCalendar(options: DeleteCalendarOptions) => Promise<void>

Deletes a calendar by id.

Since: 5.2.0

Platform: Android, iOS

modifyCalendar(...)

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

Modifies a calendar with options.

Since: 7.2.0

Platform: Android, iOS

createRemindersList(...)

createRemindersList(options: CreateRemindersListOptions) => Promise<CreateRemindersListResult>

Creates a new reminders list.

Returns: Promise<CreateRemindersListResult>

Since: 8.1.0

Platform: iOS

deleteRemindersList(...)

deleteRemindersList(options: DeleteRemindersListOptions) => Promise<void>

Deletes a reminders list.

Since: 8.2.0

Platform: iOS

fetchAllRemindersSources()

fetchAllRemindersSources() => Promise<FetchAllCalendarSourcesResult>

Retrieves a list of calendar sources.

Returns: Promise<FetchAllCalendarSourcesResult>

Since: 6.6.0

Platform: iOS

openReminders()

openReminders() => Promise<void>

Opens the reminders app.

Since: 7.1.0

Platform: iOS

getDefaultRemindersList()

getDefaultRemindersList() => Promise<GetDefaultRemindersListResult>

Retrieves the default reminders list.

Returns: Promise<GetDefaultRemindersListResult>

Since: 7.1.0

Platform: iOS

getRemindersLists()

getRemindersLists() => Promise<GetRemindersListsResult>

Retrieves all available reminders lists.

Returns: Promise<GetRemindersListsResult>

Since: 7.1.0

Platform: iOS

createReminder(...)

createReminder(options: CreateReminderOptions) => Promise<CreateReminderResult>

Creates a reminder.

Returns: Promise<CreateReminderResult>

Since: 0.5.0

Platform: iOS

deleteRemindersById(...)

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

Deletes multiple reminders.

Returns: Promise<{ result: DeleteRemindersByIdResult; }>

Since: 5.3.0

Platform: iOS

deleteReminder(...)

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

Deletes a reminder.

Since: 7.1.0

Platform: iOS

modifyReminder(...)

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

Modifies a reminder.

Since: 6.7.0

Platform: iOS

getReminderById(...)

getReminderById(options: GetReminderByIdOptions) => Promise<GetReminderByIdResult>

Retrieves a reminder by id.

Returns: Promise<GetReminderByIdResult>

Since: 7.1.0

Platform: iOS

getRemindersFromLists(...)

getRemindersFromLists(options: GetRemindersFromListsOptions) => Promise<GetRemindersFromListsResult>

Retrieves reminders from multiple lists.

Returns: Promise<GetRemindersFromListsResult>

Since: 5.3.0

Platform: iOS

deleteReminderWithPrompt(...)

deleteReminderWithPrompt(options: DeleteReminderWithPromptOptions) => Promise<DeleteReminderWithPromptResult>

Opens a dialog to delete a reminder.

Returns: Promise<DeleteReminderWithPromptResult>

Since: 7.2.0

Platform: iOS

updateRemindersList(...)

updateRemindersList(options: UpdateRemindersListOptions) => Promise<UpdateRemindersListResult>

Updates a reminders list.

Returns: Promise<UpdateRemindersListResult>

Since: 8.2.0

Platform: iOS

Interfaces

CheckPermissionOptions

Options for {@link CalendarAccess#checkPermission}.

RequestPermissionOptions

Options for {@link CalendarAccess#requestPermission}.

CreateEventWithPromptResult

CreateEventWithPromptOptions

EventRecurrenceRule

ModifyEventWithPromptOptions

CreateEventResult

CreateEventOptions

EventGuest

ModifyEventOptions