@capgo/capacitor-calendar

Create, read, update and delete calendar events from your Capacitor app, or open the native event editor, on iOS and Android. On iOS you also get full access to Reminders.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-calendar in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-calendar to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Native editor: createEventWithPrompt() and modifyEventWithPrompt() open the system event editor. deleteEventWithPrompt() asks for confirmation, with a plugin dialog on Android.
• Events API: createEvent(), modifyEvent(), deleteEvent(), deleteEventsById() and listEventsInRange().
• Calendars: listCalendars(), getDefaultCalendar(), createCalendar(), modifyCalendar() and deleteCalendar().
• Reminders on iOS: createReminder(), modifyReminder(), getRemindersFromLists() and more.
• Fine-grained permissions: write-only and full calendar access, read-only access on Android, plus reminders access.
• Platforms: iOS and Android. iOS uses EventKit, Android uses CalendarContract. Reminders are iOS only. Not available on web.

Native calendar and reminders access for Capacitor apps. Use it to request calendar permissions, create and edit events, open the system calendar UI, list calendars and events, and manage Reminders on iOS.

This package is a Capgo-maintained version of the calendar plugin originally built by Ehsan Barooni, ported to the Capgo Capacitor plugin template and Capacitor 8.

Table of Contents

• Installation
• Demo
• Setup
• Quick Start
• Common Recipes
• Platform Support
• Compatibility
• Documentation
• Changelog
• API
• License and Attribution

Installation

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-calendar` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-calendar
npx cap sync

Demo

iOS	Android

Setup

This plugin uses native calendar APIs, so each platform needs permission configuration before you request access at runtime.

Official platform references:

• iOS: Migrating to the latest Calendar access levels
• Android: Calendar Provider user permissions

iOS

Add the usage descriptions your app needs to ios/App/App/Info.plist. iOS 17 and newer distinguish between write-only and full calendar access.

<key>NSCalendarsUsageDescription</key>
<string>This app needs calendar access.</string>
<key>NSCalendarsWriteOnlyAccessUsageDescription</key>
<string>This app needs permission to add calendar events.</string>
<key>NSCalendarsFullAccessUsageDescription</key>
<string>This app needs permission to read and manage calendar events.</string>
<key>NSRemindersUsageDescription</key>
<string>This app needs reminders access.</string>
<key>NSRemindersFullAccessUsageDescription</key>
<string>This app needs permission to read and manage reminders.</string>

Only include the keys that match the APIs your app calls. For example, an app that only creates calendar events with write-only access does not need the Reminders keys.

Android

Add the permissions your app needs to android/app/src/main/AndroidManifest.xml:

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

Then request the matching permission at runtime before reading or writing calendar data.

Quick Start

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

const permission = await CapacitorCalendar.requestFullCalendarAccess();

if (permission.result !== 'granted') {
  throw new Error('Calendar permission was not granted');
}

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

const { id } = await CapacitorCalendar.createEvent({
  title: 'Product review',
  location: 'Capgo',
  startDate,
  endDate,
  description: 'Created with @capgo/capacitor-calendar',
});

console.log('Created event', id);

Dates are Unix timestamps in milliseconds.

Common Recipes

Open the native event editor

await CapacitorCalendar.createEventWithPrompt({
  title: 'Planning session',
  location: 'Office',
  startDate: Date.now() + 24 * 60 * 60 * 1000,
  endDate: Date.now() + 25 * 60 * 60 * 1000,
});

On Android, createEventWithPrompt and modifyEventWithPrompt always return null. List events afterward if you need to find the created event ID.

List upcoming events

const now = Date.now();
const oneWeekFromNow = now + 7 * 24 * 60 * 60 * 1000;

const { result: events } = await CapacitorCalendar.listEventsInRange({
  from: now,
  to: oneWeekFromNow,
});

Choose a calendar

const { result: calendars } = await CapacitorCalendar.listCalendars();
const { result: defaultCalendar } = await CapacitorCalendar.getDefaultCalendar();

const calendarId = defaultCalendar?.id ?? calendars[0]?.id;

selectCalendarsWithPrompt is available on iOS when you want to show the system calendar picker.

Create an iOS reminder

const permission = await CapacitorCalendar.requestFullRemindersAccess();

if (permission.result === 'granted') {
  await CapacitorCalendar.createReminder({
    title: 'Send launch notes',
    dueDate: Date.now() + 2 * 24 * 60 * 60 * 1000,
    notes: 'Created with @capgo/capacitor-calendar',
  });
}

Reminder APIs are iOS-only.

Platform Support

The web implementation exists only as a Capacitor stub and rejects native-only calls.

Compatibility

Documentation

The generated API reference is below. The source type definitions are in src/definitions.ts, and the package homepage is capgo.app/docs/plugins/calendar.

For compatibility with older code, requestPermission(...) and requestAllPermissions() are still available. New apps should prefer requestWriteOnlyCalendarAccess(), requestReadOnlyCalendarAccess(), requestFullCalendarAccess(), and requestFullRemindersAccess().

Changelog

See CHANGELOG.md for release notes.

License and Attribution

This package is released under MPL-2.0. The original @ebarooni/capacitor-calendar project was released under MIT by Ehsan Barooni; see THIRD_PARTY_NOTICES.md for attribution.

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(...)
• fetchAllRemindersSources()
• openReminders()
• getDefaultRemindersList()
• getRemindersLists()
• createReminder(...)
• deleteRemindersById(...)
• deleteReminder(...)
• modifyReminder(...)
• getReminderById(...)
• getRemindersFromLists(...)
• deleteReminderWithPrompt(...)
• Interfaces
• Type Aliases
• Enums

checkPermission(...)

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

Retrieves the current permission state for a given scope.

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

checkAllPermissions()

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

Retrieves the current state of all permissions.

Returns: Promise<{ result: CheckAllPermissionsResult; }>

Since: 0.1.0

requestPermission(...)

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

Requests permission for a given scope.

Returns: Promise<{ result: PermissionState; }>

Since: 0.1.0

requestAllPermissions()

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

Requests permission for all calendar and reminder permissions.

Returns: Promise<{ result: CheckAllPermissionsResult; }>

Since: 0.1.0

requestWriteOnlyCalendarAccess()

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

Requests write access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

requestReadOnlyCalendarAccess()

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

Requests read access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

requestFullCalendarAccess()

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

Requests read and write access to the calendar.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

requestFullRemindersAccess()

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

Requests read and write access to reminders.

Returns: Promise<{ result: PermissionState; }>

Since: 5.4.0

createEventWithPrompt(...)

createEventWithPrompt(options?: CreateEventWithPromptOptions | undefined) => Promise<{ id: string | null; }>

Opens the system calendar interface to create a new event. On Android this always returns null; fetch events to find the newly created event ID.

Returns: Promise<{ id: string | null; }>

Since: 0.1.0

modifyEventWithPrompt(...)

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

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

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

Since: 6.6.0

createEvent(...)

createEvent(options: CreateEventOptions) => Promise<{ id: string; }>

Creates an event in the calendar.

Returns: Promise<{ id: string; }>

Since: 0.4.0

modifyEvent(...)

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

Modifies an event.

Since: 6.6.0

deleteEventsById(...)

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

Deletes multiple events.

Returns: Promise<{ result: DeleteEventsByIdResult; }>

Since: 0.11.0

deleteEvent(...)

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

Deletes an event.

Since: 7.1.0

deleteEventWithPrompt(...)

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

Opens a dialog to delete an event.

Returns: Promise<{ deleted: boolean; }>

Since: 7.1.0

listEventsInRange(...)

listEventsInRange(options: ListEventsInRangeOptions) => Promise<{ result: CalendarEvent[]; }>

Retrieves events within a date range.

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

Since: 0.10.0

commit()

commit() => Promise<void>

Saves pending iOS calendar changes.

Since: 7.1.0

selectCalendarsWithPrompt(...)

selectCalendarsWithPrompt(options?: SelectCalendarsWithPromptOptions | undefined) => Promise<{ result: Calendar[]; }>

Opens a system interface to choose one or multiple calendars.

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

Since: 0.2.0

fetchAllCalendarSources()

fetchAllCalendarSources() => Promise<{ result: CalendarSource[]; }>

Retrieves a list of calendar sources.

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

Since: 6.6.0

listCalendars()

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

Retrieves all available calendars.

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

Since: 7.1.0

getDefaultCalendar()

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

Retrieves the default calendar.

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

Since: 0.3.0

openCalendar(...)

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

Opens the calendar app.

Since: 7.1.0

createCalendar(...)

createCalendar(options: CreateCalendarOptions) => Promise<{ id: string; }>

Creates a calendar.

Returns: Promise<{ id: string; }>

Since: 5.2.0

deleteCalendar(...)

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

Deletes a calendar by ID.

Since: 5.2.0

modifyCalendar(...)

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

Modifies a calendar.

Since: 7.2.0

fetchAllRemindersSources()

fetchAllRemindersSources() => Promise<{ result: CalendarSource[]; }>

Retrieves a list of reminder sources.

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

Since: 6.6.0

openReminders()

openReminders() => Promise<void>

Opens the reminders app.

Since: 7.1.0

getDefaultRemindersList()

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

Retrieves the default reminders list.

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

Since: 7.1.0

getRemindersLists()

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

Retrieves all available reminders lists.

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

Since: 7.1.0

createReminder(...)

createReminder(options: CreateReminderOptions) => Promise<{ id: string; }>

Creates a reminder.

Returns: Promise<{ id: string; }>

Since: 0.5.0

deleteRemindersById(...)

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

Deletes multiple reminders.

Returns: Promise<{ result: DeleteRemindersByIdResult; }>

Since: 5.3.0

deleteReminder(...)

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

Deletes a reminder.

Since: 7.1.0

modifyReminder(...)

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

Modifies a reminder.

Since: 6.7.0

getReminderById(...)

getReminderById(options: GetReminderByIdOptions) => Promise<{ result: Reminder | null; }>

Retrieves a reminder by ID.

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

Since: 7.1.0

getRemindersFromLists(...)

getRemindersFromLists(options: GetRemindersFromListsOptions) => Promise<{ result: Reminder[]; }>

Retrieves reminders from multiple lists.

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

Since: 5.3.0

deleteReminderWithPrompt(...)

deleteReminderWithPrompt(options: DeleteReminderWithPromptOptions) => Promise<{ deleted: boolean; }>

Opens a dialog to delete a reminder.

Returns: Promise<{ deleted: boolean; }>

Since: 7.2.0

Interfaces

CreateEventWithPromptOptions

EventRecurrenceRule

ModifyEventWithPromptOptions

CreateEventOptions

EventGuest

ModifyEventOptions

DeleteEventsByIdResult

DeleteEventsByIdOptions

DeleteEventOptions

DeleteEventWithPromptOptions

CalendarEvent

ListEventsInRangeOptions

Calendar

CalendarSource

SelectCalendarsWithPromptOptions

OpenCalendarOptions

CreateCalendarOptions

DeleteCalendarOptions

ModifyCalendarOptions

CreateReminderOptions