@ebarooni/capacitor-calendar

Full-featured Capacitor plugin for calendar and reminders access on iOS, Android, and the web. On iOS and Android, manage permissions, create, modify, and delete events and reminders programmatically or via the native UI, query events in a date range, and list available calendars. On the web, create events as ICS files that users can add to their calendar.

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

• iOS — Full support (including Reminders and advanced features)
• Android — Strong support for all core calendar features
• Web — Partial support (create events as .ics files)

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

@ebarooni/capacitor-calendar ships an official MCP server so AI coding assistants can work with the plugin accurately.

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

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

• Installation
• Demo
• Setup
• Quick Start
• Usage Examples
• Documentation
• Changelog
• Breaking Changes
• API
• Contributing
• License

npm install @ebarooni/capacitor-calendar
npx cap sync

iOS 26	Android 17

This plugin works with native calendar APIs, so you'll need to configure permissions on each platform before requesting access at runtime.

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

Don't forget to request the matching runtime permissions before reading from or writing 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

Here's a simple example to get you up and running quickly:

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

Use the system calendar UI to let users create or edit events:

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

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 the system calendar interface to create a new event. On Android always returns null for id. Fetch the events to find the ID of the newly created event.

Returns: Promise<CreateEventWithPromptResult>

Since: 0.1.0

Platform: Android, iOS

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, there is no system calendar store: builds an .ics File as ics. The app must download or open that file (for example with downloadIcsFile(...)); this method does not trigger a download.

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<{ result: CalendarSource[]; }>

Retrieves a list of calendar sources.

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

Since: 6.6.0

Platform: iOS

openReminders() => Promise<void>

Opens the reminders app.

Since: 7.1.0

Platform: iOS

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

Retrieves the default reminders list.

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

Since: 7.1.0

Platform: iOS

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

Retrieves all available reminders lists.

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

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>

Retrieve 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<{ deleted: boolean; }>

Opens a dialog to delete a reminder.

Returns: Promise<{ deleted: boolean; }>

Since: 7.2.0

Platform: iOS

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

Update a reminders list with options.

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'

See CONTRIBUTING.md for guidelines.

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