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

• 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

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

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.

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

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

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

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

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.

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.

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>

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

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.

Defined codes:

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

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

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

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

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(),
});

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

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',
  });
}

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

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

See BREAKING.md for breaking changes and migration steps.

• 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(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() => 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(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() => 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() => Promise<{ result: PermissionState; }>

Requests write access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: Android, iOS

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

Requests read access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: Android

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

Requests read and write access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

Platform: Android, iOS

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(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(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(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(options: ModifyEventOptions) => Promise<void>

Modifies an event.

Since: 6.6.0

Platform: Android, iOS

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

Deletes multiple events.

Returns: Promise<{ result: DeleteEventsByIdResult; }>

Since: 0.11.0

Platform: Android, iOS

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

Deletes an event.

Since: 7.1.0

Platform: Android, iOS

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(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() => Promise<void>

Saves pending calendar changes.

Since: 7.1.0

Platform: iOS

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() => 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() => 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(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(options?: OpenCalendarOptions | undefined) => Promise<void>

Opens the calendar app.

Since: 7.1.0

Platform: Android, iOS

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(options: DeleteCalendarOptions) => Promise<void>

Deletes a calendar by id.

Since: 5.2.0

Platform: Android, iOS

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

Modifies a calendar with options.

Since: 7.2.0

Platform: Android, iOS

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

Creates a new reminders list.

Returns: Promise<CreateRemindersListResult>

Since: 8.1.0

Platform: iOS

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

Deletes a reminders list.

Since: 8.2.0

Platform: iOS

fetchAllRemindersSources() => Promise<FetchAllCalendarSourcesResult>

Retrieves a list of calendar sources.

Returns: Promise<FetchAllCalendarSourcesResult>

Since: 6.6.0

Platform: iOS

openReminders() => Promise<void>

Opens the reminders app.

Since: 7.1.0

Platform: iOS

getDefaultRemindersList() => Promise<GetDefaultRemindersListResult>

Retrieves the default reminders list.

Returns: Promise<GetDefaultRemindersListResult>

Since: 7.1.0

Platform: iOS

getRemindersLists() => Promise<GetRemindersListsResult>

Retrieves all available reminders lists.

Returns: Promise<GetRemindersListsResult>

Since: 7.1.0

Platform: iOS

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

Creates a reminder.

Returns: Promise<CreateReminderResult>

Since: 0.5.0

Platform: iOS

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

Deletes multiple reminders.

Returns: Promise<{ result: DeleteRemindersByIdResult; }>

Since: 5.3.0

Platform: iOS

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

Deletes a reminder.

Since: 7.1.0

Platform: iOS

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

Modifies a reminder.

Since: 6.7.0

Platform: iOS

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

Retrieves a reminder by id.

Returns: Promise<GetReminderByIdResult>

Since: 7.1.0

Platform: iOS

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

Retrieves reminders from multiple lists.

Returns: Promise<GetRemindersFromListsResult>

Since: 5.3.0

Platform: iOS

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

Opens a dialog to delete a reminder.

Returns: Promise<DeleteReminderWithPromptResult>

Since: 7.2.0

Platform: iOS

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

Updates a reminders list.

Returns: Promise<UpdateRemindersListResult>

Since: 8.2.0

Platform: iOS

Options for {@link CalendarAccess#checkPermission}.

Options for {@link CalendarAccess#requestPermission}.

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

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

{ [P in K]: T; }

'daily' | 'weekly' | 'monthly' | 'yearly'

'canceled' | 'saved' | 'deleted'

Named iOS system color.

'blue' | 'brown' | 'gray' | 'green' | 'indigo' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'

A reminders list on iOS.

Same shape as {@link Calendar} today. Android-only calendar fields (visible, accountName, ownerAccount, maxReminders, internalTitle, location) are always null on reminder list payloads.

See CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License. See LICENSE for details.