@ebarooni/capacitor-calendar

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 — Partial support (create event)

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.

MCP Server

@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
API
Contributing
License

Installation

npm install @ebarooni/capacitor-calendar
npx cap sync

Demo

iOS 26	Android 17

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:

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.

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
Android: Calendar Provider User Permissions

Quick Start

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

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:

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

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

Param	Type
`options`	`CheckPermissionOptions`

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.

Param	Type
`options`	`RequestPermissionOptions`

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

Param	Type
`options`	`CreateEventWithPromptOptions`

Returns: Promise<CreateEventWithPromptResult>

Since: 0.1.0

Platform: Android, iOS

modifyEventWithPrompt(...)

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(...)

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.

Param	Type
`options`	`CreateEventOptions`

Returns: Promise<CreateEventResult>

Since: 0.4.0

Platform: Android, iOS, Web

modifyEvent(...)

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

Modifies an event.

Param	Type
`options`	`ModifyEventOptions`

Since: 6.6.0

Platform: Android, iOS

deleteEventsById(...)

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(...)

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

Deletes an event.

Param	Type
`options`	`DeleteEventOptions`

Since: 7.1.0

Platform: Android, iOS

deleteEventWithPrompt(...)

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(...)

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

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.

Param	Type
`options`	`ListEventsInRangeOptions`

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

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.

Param	Type
`options`	`SelectCalendarsWithPromptOptions`

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.

Param	Type
`options`	`GetDefaultCalendarOptions`

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

Since: 0.3.0

Platform: Android, iOS

openCalendar(...)

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

Opens the calendar app.

Param	Type
`options`	`OpenCalendarOptions`

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.

Param	Type
`options`	`CreateCalendarOptions`

Returns: Promise<CreateCalendarResult>

Since: 5.2.0

Platform: Android, iOS

deleteCalendar(...)

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

Deletes a calendar by id.

Param	Type
`options`	`DeleteCalendarOptions`

Since: 5.2.0

Platform: Android, iOS

modifyCalendar(...)

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

Modifies a calendar with options.

Param	Type
`options`	`ModifyCalendarOptions`

Since: 7.2.0

Platform: Android, iOS

createRemindersList(...)

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

Creates a new reminders list.

Param	Type
`options`	`CreateRemindersListOptions`

Returns: Promise<CreateRemindersListResult>

Since: 8.1.0

Platform: iOS

deleteRemindersList(...)

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

Deletes a reminders list.

Param	Type
`options`	`DeleteRemindersListOptions`

Since: 8.2.0

Platform: iOS

fetchAllRemindersSources()

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

Retrieves a list of calendar sources.

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

Since: 6.6.0

Platform: iOS

openReminders()

openReminders() => Promise<void>

Opens the reminders app.

Since: 7.1.0

Platform: iOS

getDefaultRemindersList()

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

Retrieves the default reminders list.

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

Since: 7.1.0

Platform: iOS

getRemindersLists()

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

Retrieves all available reminders lists.

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

Since: 7.1.0

Platform: iOS

createReminder(...)

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

Creates a reminder.

Param	Type
`options`	`CreateReminderOptions`

Returns: Promise<{ id: string; }>

Since: 0.5.0

Platform: iOS

deleteRemindersById(...)

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

Deletes multiple reminders.

Param	Type
`options`	`DeleteRemindersByIdOptions`

Returns: Promise<{ result: DeleteRemindersByIdResult; }>

Since: 5.3.0

Platform: iOS

deleteReminder(...)

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

Deletes a reminder.

Param	Type
`options`	`DeleteReminderOptions`

Since: 7.1.0

Platform: iOS

modifyReminder(...)

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

Modifies a reminder.

Param	Type
`options`	`ModifyReminderOptions`

Since: 6.7.0

Platform: iOS

getReminderById(...)

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(...)

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(...)

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(...)

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

Update a reminders list with options.

Param	Type
`options`	`UpdateRemindersListOptions`

Returns: Promise<UpdateRemindersListResult>

Since: 8.2.0

Platform: iOS

Interfaces

CheckPermissionOptions

Options for CalendarAccess#checkPermission.

Prop	Type	Description	Since	Platform
`scope`	`CalendarPermissionScope`	The permission scope to check. On Android, `readReminders` and `writeReminders` resolve to `"prompt"` (reminders are not supported on Android).	8.3.1	Android, iOS

RequestPermissionOptions

Options for CalendarAccess#requestPermission.

Prop	Type	Description	Since	Platform
`scope`	`CalendarPermissionScope`	The permission scope to request.	8.3.1	Android, iOS

CreateEventWithPromptResult

Prop	Type	Description	Since	Platform
`id`	`string \| null`	The identifier of the created event. Always `null` on Android. Present on iOS when the user saves.	0.1.0	Android, iOS

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

CreateEventResult

Prop	Type	Description	Since	Platform
`ics`	`File`	An `.ics` file (`text/calendar`) with one `VEVENT`. Present only on Web. The plugin does not write to a calendar store or start a download; use `downloadIcsFile(...)` or pass the `File` to another API.	8.5.0	Web
`id`	`string \| null`	The identifier of the created event. Always `null` on Web. Present on Android and iOS after a successful create.	0.4.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, Web
`attendees`	`EventGuest[]`	The event guests.		7.1.0	Android, Web
`availability`	`EventAvailability`			7.1.0	Android, iOS, Web
`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, Web
`duration`	`string`	Duration of the event in RFC2445 format.		7.1.0	Android
`endDate`	`number`			0.1.0	Android, iOS, Web
`icsFileName`	`string`	Download filename for the `.ics` file. When omitted, a name is derived from `title` (fallback `event.ics`). If the value has no `.ics` extension, `.ics` is appended.		8.5.0	Web
`isAllDay`	`boolean`			0.1.0	Android, iOS, Web
`location`	`string`			0.1.0	Android, iOS, Web
`organizer`	`string`	Email of the event organizer.		7.1.0	Android, Web
`recurrence`	`EventRecurrenceRule`	Rules for creating a recurring event.		7.3.0	Android, iOS, Web
`startDate`	`number`			0.1.0	Android, iOS, Web
`title`	`string`			0.4.0	Android, iOS, Web
`url`	`string`			0.1.0	iOS, Web

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
`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.3.0	iOS
`ids`	`string[]`			7.1.0
`span`	`EventSpan`	How much of a recurring series to delete. On Android, `THIS_EVENT` cannot target a single recurring occurrence here — use `deleteEvent` with `instanceDate`. Those ids are reported in `failed`.	`EventSpan.THIS_EVENT`	7.1.0	Android, iOS

DeleteEventOptions

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.3.0	iOS
`id`	`string`	The ID of the event to delete.		7.1.0	Android, iOS
`instanceDate`	`number`	The start time of the occurrence to delete, in milliseconds since the epoch. Use `startDate` from `listEventsInRange`. On Android, required for `THIS_EVENT` on recurring events. If omitted with `THIS_AND_FUTURE_EVENTS`, the whole series is deleted.		8.3.0	Android
`span`	`EventSpan`	How much of a recurring series to delete.	`EventSpan.THIS_EVENT`	7.1.0	Android, iOS

DeleteEventWithPromptOptions

Prop	Type	Description	Default	Since	Platform
`cancelButtonText`	`string`	Text to show on the cancel button.	`'Cancel'`	7.1.0	Android, iOS
`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.3.0	iOS
`confirmButtonText`	`string`	Text to show on the confirm button.	`'Delete'`	7.1.0	Android, iOS
`id`	`string`	The ID of the event to delete.		7.1.0	Android, iOS
`instanceDate`	`number`	The start time of the occurrence to delete, in milliseconds since the epoch. Use `startDate` from `listEventsInRange`. On Android, required for `THIS_EVENT` on recurring events. If omitted with `THIS_AND_FUTURE_EVENTS`, the whole series is deleted.		8.3.0	Android
`message`	`string`	Message of the dialog.		7.1.0	Android, iOS
`span`	`EventSpan`	How much of a recurring series to delete.	`EventSpan.THIS_EVENT`	7.1.0	Android, iOS
`title`	`string`	Title of the dialog.		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 start of the range, in milliseconds since the epoch. Events still in progress at this time are included.	7.1.0
`to`	`number`	The end of the range, in milliseconds since the epoch. Events that begin at or after this time are typically excluded; prefer the next day's start when querying a single calendar day.	7.1.0

SelectCalendarsWithPromptResult

Prop	Type	Description	Since	Platform
`result`	`Calendar[]`	Calendars the user confirmed in the chooser. Empty when the user cancels.	8.4.0	iOS

Calendar

Prop	Type	Description	Since	Platform
`id`	`string`		7.1.0	Android, iOS
`title`	`string \| null`	Display title of the calendar. May be `null` when the platform does not provide a title.	7.1.0	Android, iOS
`internalTitle`	`string \| null`	Internal name of the calendar (`CalendarContract.Calendars.NAME`).	7.1.0	Android
`color`	`string \| null`	Calendar color as a hex string. Format: `#RRGGBB` when opaque; `#RRGGBBAA` when alpha is below fully opaque. May be `null` when the platform does not provide a color.	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	Platform
`type`	`CalendarSourceType`	7.1.0	iOS
`id`	`string`	7.1.0	iOS
`title`	`string`	7.1.0	iOS

SelectCalendarsWithPromptOptions

Prop	Type	Description	Default	Since
`displayStyle`	`CalendarChooserDisplayStyle`		`CalendarChooserDisplayStyle.ALL_CALENDARS`	7.1.0
`multiple`	`boolean`	Allow multiple selections.	`false`	7.1.0

FetchAllCalendarSourcesResult

Prop	Type	Description	Since	Platform
`result`	`CalendarSource[]`	All calendar sources (accounts) known to EventKit.	8.4.0	iOS

ListCalendarsResult

Prop	Type	Description	Since	Platform
`result`	`Calendar[]`	All available calendars.	8.4.0	Android, iOS

GetDefaultCalendarOptions

Prop	Type	Description	Default	Since	Platform
`useFallbackCalendar`	`boolean`	When there is no system default calendar, use the first available calendar.	`false`	8.4.0	Android, iOS

OpenCalendarOptions

Prop	Type	Description	Default	Since	Platform
`date`	`number`	The date to open the calendar at, in milliseconds since the epoch.	`Date.now()`	7.1.0	Android, iOS

CreateCalendarResult

Prop	Type	Description	Since	Platform
`id`	`string`	Identifier of the newly created calendar.	8.4.0	Android, iOS

CreateCalendarOptions

Prop	Type	Description	Default	Since	Platform
`title`	`string`			5.2.0	Android, iOS
`color`	`string`	The color of the calendar as `#RRGGBB` or `#RRGGBBAA`. When omitted, Android and iOS use `#007AFF` (light-mode iOS system blue).	`#007AFF`	5.2.0	Android, iOS
`sourceId`	`string`	The EventKit source (account) where the calendar should be created. If provided, it must match an existing source from `fetchAllCalendarSources()`. If omitted, iCloud is used when available, otherwise the local source.		5.2.0	iOS
`accountName`	`string`	The account under which the calendar is registered. Required on Android. Typically an email address.		7.1.0	Android
`ownerAccount`	`string`	The owner of the calendar. Required on Android. Typically an email address.		7.1.0	Android

DeleteCalendarOptions

Prop	Type	Since	Platform
`id`	`string`	7.1.0	Android, iOS

ModifyCalendarOptions

Prop	Type	Description	Since	Platform
`id`	`string`		7.2.0	Android, iOS
`title`	`string`	Display title of the calendar. On Android this updates both `CALENDAR_DISPLAY_NAME` (`title`) and `Calendars.NAME` (`internalTitle`).	7.2.0	Android, iOS
`color`	`string`	The color of the calendar as `#RRGGBB` or `#RRGGBBAA`.	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. On Android, reminders are not supported. `checkPermission` and `checkAllPermissions` return `"prompt"` for this scope. `requestPermission` rejects with `Invalid scope.`.	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. On Android, reminders are not supported. `checkPermission` and `checkAllPermissions` return `"prompt"` for this scope. `requestPermission` rejects with `Invalid scope.`.	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	Description	Since
`THIS_EVENT`	Only the identified event or occurrence.	7.1.0
`THIS_AND_FUTURE_EVENTS`	The identified occurrence and future occurrences in the series.	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 for guidelines.

License

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

@ebarooni/capacitor-calendar

@ebarooni/capacitor-calendar

Core Features

Supported Platforms

Why this plugin?

MCP Server

Table of Contents

Installation

Demo

Setup

Android

iOS

Official References

Quick Start

Usage Examples

Open the native event editor

List events in a range

Working with Calendars

Create a Reminder (iOS only)

Documentation

Changelog

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

CheckPermissionOptions

RequestPermissionOptions

CreateEventWithPromptResult

CreateEventWithPromptOptions

EventRecurrenceRule

ModifyEventWithPromptOptions

CreateEventResult

CreateEventOptions

EventGuest

ModifyEventOptions

DeleteEventsByIdResult

DeleteEventsByIdOptions

DeleteEventOptions

DeleteEventWithPromptOptions

CalendarEvent

ListEventsInRangeOptions

SelectCalendarsWithPromptResult

Calendar