This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Expo Calendar (next)
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
If 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 (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.
Example app.json with config plugin
Configurable properties
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
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.
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
Check or request permissions to access the calendar.
This uses both getCalendarPermissionsAsync and requestCalendarPermissionsAsync to interact
with the permissions.
[PermissionResponse | null, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]Example
const [status, requestPermission] = Calendar.useCalendarPermissions();
Check or request permissions to access reminders.
This uses both getRemindersPermissionsAsync and requestRemindersPermissionsAsync to interact
with the permissions.
[PermissionResponse | null, 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: string | null
stringID of the source to be used for the calendar. Likely the same as the source for any other locally stored calendars.
ExpoCalendar Methods
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>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 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.
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: string | null
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: RecurrenceRule | null
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
Deletes the event.
Promise<void>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.
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.
Returns an event instance for a given event (or instance of a recurring event).
ExpoCalendarEventAn event instance.
Launches the calendar UI provided by the OS to preview an event.
Promise<OpenEventDialogResult>A promise which resolves with information about the dialog result.
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: RecurrenceRule | null
unionDate object or string representing the start date of the reminder task.
Acceptable values are: string | Date
ExpoCalendarReminder Methods
Deletes the reminder.
Promise<void>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
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();
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>Gets an array of Source objects with details about the different sources stored on the device.
Source[]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>Asks the user to grant permissions for accessing user's reminders.
Promise<PermissionResponse>Types
The result of presenting a calendar dialog for creating or editing an event.
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.
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
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.
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.
A source account that owns a particular calendar. Expo apps will typically not need to interact with Source objects.
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.
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.
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: