This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 54).
A library that provides an API for interacting with the device's system calendars, events, reminders, and associated records.
Thenextversion of the Calendar API is included in theexpo-calendarlibrary. It can be used alongside the previous API, and offers a simplified, object oriented way of performing calendar operations.
To provide quicker updates,expo-calendar/nextis currently unsupported in Expo Go and Snack. To use it, create a development build.
expo-calendar provides an API for interacting with the device's system calendars, events, reminders, and associated records.
Additionally, it provides methods to launch the system-provided calendar UI to allow the user to view or edit events. On iOS, they present either EKEventViewController or EKEventEditViewController as a modal.
Installation
- npx expo install expo-calendarIf you are installing this in an existing React Native app, make sure to install expo in your project.
Configuration in app config
You can configure expo-calendar using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect.
Example app.json with config plugin
{ "expo": { "plugins": [ [ "expo-calendar", { "calendarPermission": "The app needs to access your calendar." } ] ] } }
Configurable properties
| Name | Default | Description |
|---|---|---|
calendarPermission | "Allow $(PRODUCT_NAME) to access your calendar" | Only for: iOS A string to set the |
remindersPermission | "Allow $(PRODUCT_NAME) to access your reminders" | Only for: iOS A string to set the |
Are you using this library in an existing React Native app?
If you're not using Continuous Native Generation (CNG) (you're using native ios project manually), then you need to configure following permissions in your native project:
-
For iOS, add
NSCalendarsUsageDescriptionandNSRemindersUsageDescriptionto your project's ios/[app]/Info.plist:<key>NSCalendarsUsageDescription</key> <string>Allow $(PRODUCT_NAME) to access your calendar</string> <key>NSRemindersUsageDescription</key> <string>Allow $(PRODUCT_NAME) to access your reminders</string>
Usage
import * as Calendar from 'expo-calendar/next'; import { useEffect } from 'react'; import { StyleSheet, View, Text, Button } from 'react-native'; const BasicUsage = () => { useEffect(() => { (async () => { const { status } = await Calendar.requestCalendarPermissions(); if (status === 'granted') { const calendars = Calendar.getCalendars(Calendar.EntityTypes.EVENT); console.log('Here are all your calendars:'); console.log(JSON.stringify(calendars)); } })(); }, []); return ( <View style={styles.container}> <Text>Calendar Module Example</Text> <Button title="Create a new calendar" onPress={createCalendar} /> </View> ); }; async function createCalendar() { const newCalendar = await Calendar.createCalendar({ title: 'Expo Calendar', color: 'blue', entityType: Calendar.EntityTypes.EVENT, }); console.log(`Your new calendar: ${JSON.stringify(newCalendar)}`); } const styles = StyleSheet.create({ container: { flex: 1, backgroundColor: '#fff', alignItems: 'center', justifyContent: 'space-around', }, });
API
import * as Calendar from 'expo-calendar/next';
Unless specified otherwise, all dates are returned in the ISO 8601 format.
Launching system-provided calendar dialogs
| Parameter | Type | Description |
|---|---|---|
| eventData(optional) | Omit<Partial<Event>, 'id'> | A map of details for the event to be created. Default: {} |
| presentationOptions(optional) | PresentationOptions | Configuration that influences how the calendar UI is presented. |
Launches the calendar UI provided by the OS to create a new event.
Promise<DialogEventResult>A promise which resolves with information about the dialog result.
| Parameter | Type |
|---|---|
| params | CalendarDialogParams |
| presentationOptions(optional) | OpenEventPresentationOptions |
Launches the calendar UI provided by the OS to preview an event.
Promise<OpenEventDialogResult>A promise which resolves with information about the dialog result.
Hooks
| Parameter | Type |
|---|---|
| options(optional) | PermissionHookOptions<object> |
Check or request permissions to access the calendar.
This uses both getCalendarPermissionsAsync and requestCalendarPermissionsAsync to interact
with the permissions.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = Calendar.useCalendarPermissions();
| Parameter | Type |
|---|---|
| options(optional) | PermissionHookOptions<object> |
Check or request permissions to access reminders.
This uses both getRemindersPermissionsAsync and requestRemindersPermissionsAsync to interact
with the permissions.
[null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = Calendar.useRemindersPermissions();
Classes
Type: Class extends ExpoCalendar
Represents a calendar object that can be accessed and modified using the Expo Calendar Next API.
This class provides properties and methods for interacting with a specific calendar on the device, such as retrieving its events, updating its details, and accessing its metadata.
ExpoCalendar Properties
CalendarAccessLevelLevel of access that the user has for the calendar.
AttendeeType[]Attendee types that this calendar supports.
booleanBoolean value that determines whether this calendar can be modified.
EntityTypesWhether the calendar is used in the Calendar or Reminders OS app.
booleanBoolean value indicating whether this is the device's primary calendar.
booleanIndicates whether this calendar is synced and its events stored on the device.
Unexpected behavior may occur if this is not set to true.
unionInternal system name of the calendar.
Acceptable values are: null | string
stringID of the source to be used for the calendar. Likely the same as the source for any other locally stored calendars.
ExpoCalendar Methods
| Parameter | Type |
|---|---|
| details | Partial<Omit<Event, 'creationDate' | 'lastModifiedDate' | 'originalStartDate' | 'isDetached' | 'status' | 'organizer'>> |
Creates a new event in the calendar.
Promise<ExpoCalendarEvent>An instance of the created event.
Creates a new reminder in the calendar.
Promise<ExpoCalendarReminder>An instance of the created reminder.
Deletes the calendar.
Promise<void>| Parameter | Type | Description |
|---|---|---|
| calendarId | string | The ID of the calendar to get. |
Gets a calendar by its ID. Throws an error if the calendar with the given ID does not exist.
Promise<ExpoCalendar>An ExpoCalendar object representing the calendar.
Returns a calendar event list for the given date range.
Promise<ExpoCalendarEvent[]>| Parameter | Type | Description |
|---|---|---|
| startDate(optional) | null | Date | Beginning of time period to search for reminders in, or Default: null |
| endDate(optional) | null | Date | End of time period to search for reminders in, or Default: null |
| status(optional) | null | ReminderStatus | One of Default: null |
Returns a list of reminders matching the provided criteria. If startDate and endDate are defined,
returns all reminders that overlap at all with the [startDate, endDate] interval, that is, all reminders
that end after the startDate or begin before the endDate.
Promise<ExpoCalendarReminder[]>An array of ExpoCalendarReminder objects matching the search criteria.
| Parameter | Type | Description |
|---|---|---|
| details | Partial<ModifiableCalendarProperties> | A map of properties to be updated. |
Updates the provided details of an existing calendar stored on the device. To remove a property,
explicitly set it to null in details.
Promise<void>Type: Class extends ExpoCalendarAttendee
Represents a calendar attendee object.
ExpoCalendarAttendee Properties
booleanIndicates whether or not this attendee is the current OS user.
ExpoCalendarAttendee Methods
Deletes the attendee.
Promise<void>Type: Class extends ExpoCalendarEvent
Represents a calendar event object that can be accessed and modified using the Expo Calendar Next API.
ExpoCalendarEvent Properties
unionDate when the event record was created.
Acceptable values are: string | Date
unionDate object or string representing the time when the event ends.
Acceptable values are: string | Date
booleanWhether invited guests can modify the details of the event.
stringFor instances of recurring events, volatile ID representing this instance. Not guaranteed to always refer to the same instance.
booleanBoolean value indicating whether or not the event is a detached (modified) instance of a recurring event.
unionDate when the event record was last modified.
Acceptable values are: string | Date
unionLocation field of the event.
Acceptable values are: null | string
OrganizerOrganizer of the event. This property is only available on events associated with calendars that are managed by a service such as Google Calendar or iCloud. The organizer is read-only and cannot be set.
stringFor detached (modified) instances of recurring events, the ID of the original recurring event.
unionFor recurring events, the start date for the first (original) instance of the event.
Acceptable values are: string | Date
unionObject representing rules for recurring or repeating events. Set to null for one-time events.
It is either endDate or occurrence based.
Acceptable values are: null | RecurrenceRule
unionDate object or string representing the time when the event starts.
Acceptable values are: string | Date
stringTime zone the event is scheduled in.
When set to null, the event is scheduled to the device's time zone.
ExpoCalendarEvent Methods
| Parameter | Type |
|---|---|
| attendee | Attendee |
Creates a new attendee and adds it to this event.
Promise<ExpoCalendarAttendee>Deletes the event.
Promise<void>| Parameter | Type |
|---|---|
| params(optional) | CalendarDialogParamsNext |
Launches the calendar UI provided by the OS to edit or delete an event.
Promise<DialogEventResult>A promise which resolves with information about the dialog result.
| Parameter | Type | Description |
|---|---|---|
| eventId | string | The ID of the event to get. |
Gets an event by its ID. Throws an error if the event with the given ID does not exist.
Promise<ExpoCalendarEvent>An ExpoCalendarEvent object representing the event.
Gets all attendees for a given event (or instance of a recurring event).
Promise<ExpoCalendarAttendee[]>An array of Attendee associated with the specified event.
| Parameter | Type | Description |
|---|---|---|
| recurringEventOptions(optional) | RecurringEventOptions | A map of options for recurring events. Default: {} |
Returns an event instance for a given event (or instance of a recurring event).
ExpoCalendarEventAn event instance.
| Parameter | Type |
|---|---|
| params(optional) | CalendarDialogOpenParamsNext |
Launches the calendar UI provided by the OS to preview an event.
Promise<OpenEventDialogResult>A promise which resolves with information about the dialog result.
| Parameter | Type | Description |
|---|---|---|
| details | Partial<ModifiableEventProperties> | A map of properties to be updated. |
Updates the provided details of an existing calendar stored on the device. To remove a property,
explicitly set it to null in details.
Promise<void>Type: Class extends ExpoCalendarReminder
Represents a calendar reminder object that can be accessed and modified using the Expo Calendar Next API.
ExpoCalendarReminder Properties
Alarm[]Array of Alarm objects which control automated alarms to the user about the task.
unionDate object or string representing the date of completion, if completed is true.
Setting this property of a nonnull Date will automatically set the reminder's completed value to true.
Acceptable values are: string | Date
unionDate when the reminder record was created.
Acceptable values are: string | Date
unionDate object or string representing the time when the reminder task is due.
Acceptable values are: string | Date
unionDate when the reminder record was last modified.
Acceptable values are: string | Date
unionObject representing rules for recurring or repeated reminders. null for one-time tasks.
Acceptable values are: null | RecurrenceRule
unionDate object or string representing the start date of the reminder task.
Acceptable values are: string | Date
ExpoCalendarReminder Methods
Deletes the reminder.
Promise<void>| Parameter | Type | Description |
|---|---|---|
| reminderId | string | The ID of the reminder to get. |
Gets a reminder by its ID. Throws an error if the reminder with the given ID does not exist.
Promise<ExpoCalendarReminder>An ExpoCalendarReminder object representing the reminder.
Methods
| Parameter | Type | Description |
|---|---|---|
| details(optional) | Partial<Calendar> | A map of details for the calendar to be created. Default: {} |
Creates a new calendar on the device, allowing events to be added later and displayed in the OS Calendar app.
Promise<ExpoCalendar>An ExpoCalendar object representing the newly created calendar.
Check or request permissions to access the calendar.
This uses both getCalendarPermissionsAsync and requestCalendarPermissionsAsync to interact
with the permissions.
Promise<PermissionResponse>Example
const [status, requestPermission] = Calendar.useCalendarPermissions();
| Parameter | Type |
|---|---|
| type(optional) | EntityTypes |
Gets an array of ExpoCalendar shared objects with details about the different calendars stored on the device.
Promise<ExpoCalendar[]>An array of ExpoCalendar shared objects matching the provided entity type (if provided).
Gets an instance of the default calendar object.
ExpoCalendarAn ExpoCalendar object that is the user's default calendar.
Checks user's permissions for accessing user's reminders.
Promise<PermissionResponse>A promise that resolves to an object of type PermissionResponse.
Gets an array of Source objects with details about the different sources stored on the device.
Source[]An array of Source objects representing the sources found.
| Parameter | Type | Description |
|---|---|---|
| calendars | (string | ExpoCalendar)[] | An array of calendar IDs ( |
| startDate | Date | The start date of the time range to search for events. |
| endDate | Date | The end date of the time range to search for events. |
Lists events from the device's calendar. It can be used to search events in multiple calendars.
Note: If you want to search events in a single calendar, you can use
ExpoCalendar.listEventsinstead.
Promise<ExpoCalendarEvent[]>An array of ExpoCalendarEvent objects representing the events found.
Asks the user to grant permissions for accessing user's calendars.
Promise<PermissionResponse>A promise that resolves to an object of type PermissionResponse.
Asks the user to grant permissions for accessing user's reminders.
Promise<PermissionResponse>A promise that resolves to an object of type PermissionResponse.
Types
A method for having the OS automatically remind the user about a calendar item.
| Property | Type | Description |
|---|---|---|
| absoluteDate(optional) | string | Only for: iOS Date object or string representing an absolute time the alarm should occur.
Overrides |
| method(optional) | AlarmMethod | Only for: Android Method of alerting the user that this alarm should use. On iOS this is always a notification. |
| relativeOffset(optional) | number | Number of minutes from the |
| structuredLocation(optional) | AlarmLocation | - |
| Property | Type | Description |
|---|---|---|
| coords(optional) | {
latitude: number,
longitude: number
} | - |
| proximity(optional) | string | - |
| radius(optional) | number | - |
| title(optional) | string | Only for: -iOS |
| Property | Type | Description |
|---|---|---|
| id | string | ID of the event to be presented in the calendar UI. |
| instanceStartDate(optional) | string | Date | Only for: iOS Date object representing the start time of the desired instance, if looking for a single instance of a recurring event. If this is not provided and id represents a recurring event, the first instance of that event will be returned by default. |
| Property | Type | Description |
|---|---|---|
| dayOfTheWeek | DayOfTheWeek | Sunday to Saturday - |
| weekNumber(optional) | number |
|
The result of presenting a calendar dialog for creating or editing an event.
| Property | Type | Description |
|---|---|---|
| action | Extract<CalendarDialogResultActions, 'done' | 'saved' | 'canceled' | 'deleted'> | How user responded to the dialog.
On Android, this is always On iOS, it can be |
| id | string | null | The ID of the event that was created or edited. On Android, this is always On iOS, this is a string when permissions are granted and user confirms the creation or editing of an event. Otherwise, it's |
Type: Pick<ExpoCalendar, 'color' | 'title'>
Type: Pick<ExpoCalendarEvent, 'title' | 'location' | 'timeZone' | 'url' | 'notes' | 'alarms' | 'recurrenceRule' | 'availability' | 'startDate' | 'endDate' | 'allDay'>
Type: Pick<ExpoCalendarReminder, 'title' | 'location' | 'timeZone' | 'url' | 'notes' | 'alarms' | 'recurrenceRule' | 'startDate' | 'dueDate' | 'completed' | 'completionDate'>
The result of presenting the calendar dialog for opening (viewing) an event.
| Property | Type | Description |
|---|---|---|
| action | Extract<CalendarDialogResultActions, 'done' | 'canceled' | 'deleted' | 'responded'> | Indicates how user responded to the dialog.
On Android, the |
Type: PresentationOptions extended by:
| Property | Type | Description |
|---|---|---|
| allowsCalendarPreview(optional) | boolean | Only for: iOS Determines whether event can be shown in calendar day view preview. This property applies only to invitations. Default: false |
| allowsEditing(optional) | boolean | Only for: iOS Whether to allow the user to edit the previewed event. This property applies only to events in calendars created by the user. Note that if the user edits the event, the returned action is the one that user performs last.
For example, when user previews the event, confirms some edits and finally dismisses the dialog, the event is edited, but response is Default: false |
Literal Type: union
Permission expiration time. Currently, all permissions are granted permanently.
Acceptable values are: 'never' | number
Literal Type: union
Acceptable values are: PermissionHookBehavior | Options
An object obtained by permissions get and request functions.
| Property | Type | Description |
|---|---|---|
| canAskAgain | boolean | Indicates if user can be asked again for specific permission. If not, one should be directed to the Settings app in order to enable/disable the permission. |
| expires | PermissionExpiration | Determines time when the permission expires. |
| granted | boolean | A convenience boolean that indicates if the permission is granted. |
| status | PermissionStatus | Determines the status of the permission. |
| Property | Type | Description |
|---|---|---|
| startNewActivityTask(optional) | boolean | Only for: Android Whether to launch the Activity as a new task.
If Default: true |
A recurrence rule for events or reminders, allowing the same calendar item to recur multiple times. This type is based on the iOS interface which is in turn based on the iCal RFC so you can refer to those to learn more about this potentially complex interface.
Not all the combinations make sense. For example, when frequency is DAILY, setting daysOfTheMonth makes no sense.
| Property | Type | Description |
|---|---|---|
| daysOfTheMonth(optional) | number[] | Only for: iOS The days of the month this event occurs on.
|
| daysOfTheWeek(optional) | DaysOfTheWeek[] | Only for: iOS The days of the week the event should recur on. An array of |
| daysOfTheYear(optional) | number[] | Only for: iOS The days of the year this event occurs on.
|
| endDate(optional) | string | Date | Date on which the calendar item should stop recurring; overrides |
| frequency | Frequency | How often the calendar item should recur. |
| interval(optional) | number | Interval at which the calendar item should recur. For example, an Default: 1 |
| monthsOfTheYear(optional) | MonthOfTheYear[] | Only for: iOS The months this event occurs on.
This field is only valid for |
| occurrence(optional) | number | Number of times the calendar item should recur before stopping. |
| setPositions(optional) | number[] | Only for: iOS TAn array of numbers that filters which recurrences to include. For example, for an event that
recurs every Monday, passing 2 here will make it recur every other Monday.
|
| weeksOfTheYear(optional) | number[] | Only for: iOS The weeks of the year this event occurs on.
|
Options for specifying a particular instance of a recurring event. This type is used in various methods that operate on recurring events, such as updating or deleting a single occurrence or a set of future occurrences.
| Property | Type | Description |
|---|---|---|
| futureEvents(optional) | boolean | Whether future events in the recurring series should also be updated. If |
| instanceStartDate(optional) | string | Date | Date object representing the start time of the desired instance, if looking for a single instance of a recurring event. If this is not provided and id represents a recurring event, the first instance of that event will be returned by default. |
A source account that owns a particular calendar. Expo apps will typically not need to interact with Source objects.
| Property | Type | Description |
|---|---|---|
| id(optional) | string | Only for: iOS Internal ID that represents this source on the device. |
| isLocalAccount(optional) | boolean | Only for: Android Whether this source is the local phone account. Must be |
| name | string | Name for the account that owns this calendar and was used to sync the calendar to the device. |
| type | string | SourceType | Type of the account that owns this calendar and was used to sync it to the device.
If |
Enums
Enum containing all possible user responses to the calendar UI dialogs. Depending on what dialog is presented, a subset of the values applies.
CalendarDialogResultActions.canceled ＝ "canceled"The user canceled or dismissed the dialog.
CalendarDialogResultActions.done ＝ "done"On Android, this is the only possible result because the OS doesn't provide enough information to determine the user's action - the user may have canceled the dialog, modified the event, or deleted it.
On iOS, this means the user simply closed the dialog.
CalendarDialogResultActions.responded ＝ "responded"The user responded to and saved a pending event invitation.
platform ios
Permissions
Android
If you only intend to use the system-provided calendar UI, you don't need to request any permissions.
Otherwise, you must add the following permissions to your app.json inside the expo.android.permissions array.
| Android Permission | Description |
|---|---|
Allows an application to read the user's calendar data. | |
Allows an application to write the user's calendar data. |
iOS
If you only intend to create events using system-provided calendar UI with createEventInCalendarAsync, you don't need to request permissions.
The following usage description keys are used by this library: