Documentation

Hey friend! We are co-hosting a conference with Software Mansion, learn more.

Calendar

Provides an API for interacting with the device's system calendars, events, reminders, and associated records.
Requires Permissions.CALENDAR. Interacting with reminders on iOS requires Permissions.REMINDERS.
See the bottom of this page for a complete list of all possible fields for the objects used in this API.

Gets an array of calendar objects with details about the different calendars stored on the device.

  • entityType (string) -- (iOS only) Not required, but if defined, filters the returned calendars to a specific entity type. Possible values are Expo.Calendar.EntityTypes.EVENT (for calendars shown in the Calendar app) and Expo.Calendar.EntityTypes.REMINDER (for the Reminders app).

An array of calendar objects matching the provided entity type (if provided).

Creates a new calendar on the device, allowing events to be added later and displayed in the OS Calendar app.

  • details (object) --
    A map of details for the calendar to be created (see below for a description of these fields):
    • title (string) -- Required
    • color (string) -- Required
    • entityType (string) -- Required (iOS only)
    • sourceId (string) -- Required (iOS only). ID of the source to be used for the calendar. Likely the same as the source for any other locally stored calendars.
    • source (object) -- Required (Android only). Object representing the source to be used for the calendar.
      • isLocalAccount (boolean) -- Whether this source is the local phone account. Must be true if type is undefined.
      • name (string) -- Required. Name for the account that owns this calendar and was used to sync the calendar to the device.
      • type (string) -- Type of the account that owns this calendar and was used to sync it to the device. If isLocalAccount is falsy then this must be defined, and must match an account on the device along with name, or the OS will delete the calendar.
    • name (string) -- Required (Android only)
    • ownerAccount (string) -- Required (Android only)
    • timeZone (string) -- (Android only)
    • allowedAvailabilities (array) -- (Android only)
    • allowedReminders (array) -- (Android only)
    • allowedAttendeeTypes (array) -- (Android only)
    • isVisible (boolean) -- (Android only)
    • isSynced (boolean) -- (Android only)
    • accessLevel (string) -- (Android only)

A string representing the ID of the newly created calendar.

Updates the provided details of an existing calendar stored on the device. To remove a property, explicitly set it to null in details.

  • id (string) -- ID of the calendar to update. Required.
  • details (object) --
    A map of properties to be updated (see below for a description of these fields):
    • title (string)
    • sourceId (string) -- (iOS only)
    • color (string) -- (iOS only)
    • name (string) -- (Android only)
    • isVisible (boolean) -- (Android only)
    • isSynced (boolean) -- (Android only)

Deletes an existing calendar and all associated events/reminders/attendees from the device. Use with caution.

  • id (string) -- ID of the calendar to delete.

Returns all events in a given set of calendars over a specified time period. The filtering has slightly different behavior per-platform -- on iOS, all events that overlap at all with the [startDate, endDate] interval are returned, whereas on Android, only events that begin on or after the startDate and end on or before the endDate will be returned.

  • calendarIds (array) -- Array of IDs of calendars to search for events in. Required.
  • startDate (Date) -- Beginning of time period to search for events in. Required.
  • endDate (Date) -- End of time period to search for events in. Required.

An array of event objects matching the search criteria.

Returns a specific event selected by ID. If a specific instance of a recurring event is desired, the start date of this instance must also be provided, as instances of recurring events do not have their own unique and stable IDs on either iOS or Android.

  • id (string) -- ID of the event to return. Required.
  • recurringEventOptions (object) --
    A map of options for recurring events:
    • instanceStartDate (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.

An event object matching the provided criteria, if one exists.

Creates a new event on the specified calendar.

  • calendarId (string) -- ID of the calendar to create this event in (or Expo.Calendar.DEFAULT to add the calendar to the OS-specified default calendar for events). Required.
  • details (object) --
    A map of details for the event to be created (see below for a description of these fields):
    • title (string)
    • startDate (Date) -- Required.
    • endDate (Date) -- Required on Android.
    • allDay (boolean)
    • location (string)
    • notes (string)
    • alarms (Array<Alarm>)
    • recurrenceRule (RecurrenceRule)
    • availability (string)
    • timeZone (string) -- Required on Android.
    • endTimeZone (string) -- (Android only)
    • url (string) -- (iOS only)
    • organizerEmail (string) -- (Android only)
    • accessLevel (string) -- (Android only)
    • guestsCanModify (boolean) -- (Android only)
    • guestsCanInviteOthers (boolean) -- (Android only)
    • guestsCanSeeGuests (boolean) -- (Android only)

A string representing the ID of the newly created event.

Updates the provided details of an existing calendar stored on the device. To remove a property, explicitly set it to null in details.

  • id (string) -- ID of the event to be updated. Required.
  • details (object) --
    A map of properties to be updated (see below for a description of these fields):
    • title (string)
    • startDate (Date)
    • endDate (Date)
    • allDay (boolean)
    • location (string)
    • notes (string)
    • alarms (Array<Alarm>)
    • recurrenceRule (RecurrenceRule)
    • availability (string)
    • timeZone (string)
    • endTimeZone (string) -- (Android only)
    • url (string) -- (iOS only)
    • organizerEmail (string) -- (Android only)
    • accessLevel (string) -- (Android only)
    • guestsCanModify (boolean) -- (Android only)
    • guestsCanInviteOthers (boolean) -- (Android only)
    • guestsCanSeeGuests (boolean) -- (Android only)
  • recurringEventOptions (object) --
    A map of options for recurring events:
    • instanceStartDate (Date) -- Date object representing the start time of the desired instance, if wanting to update 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 updated by default.
    • futureEvents (boolean) -- Whether or not future events in the recurring series should also be updated. If true, will apply the given changes to the recurring instance specified by instanceStartDate and all future events in the series. If false, will only apply the given changes to the instance specified by instanceStartDate.

Deletes an existing event from the device. Use with caution.

  • id (string) -- ID of the event to be deleted. Required.
  • recurringEventOptions (object) --
    A map of options for recurring events:
    • instanceStartDate (Date) -- Date object representing the start time of the desired instance, if wanting to delete 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 deleted by default.
    • futureEvents (boolean) -- Whether or not future events in the recurring series should also be deleted. If true, will delete the instance specified by instanceStartDate and all future events in the series. If false, will only delete the instance specified by instanceStartDate.

Gets all attendees for a given event (or instance of a recurring event).

  • eventId (string) -- ID of the event to return attendees for. Required.
  • recurringEventOptions (object) --
    A map of options for recurring events:
    • instanceStartDate (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 eventId represents a recurring event, the attendees of the first instance of that event will be returned by default.

An array of attendee objects associated with the specified event.

Available on Android only. Creates a new attendee record and adds it to the specified event. Note that if eventId specifies a recurring event, this will add the attendee to every instance of the event.

  • eventId (string) -- ID of the event to add this attendee to. Required.
  • details (object) --
    A map of details for the attendee to be created (see below for a description of these fields):
    • id (string) Required.
    • email (string) Required.
    • name (string)
    • role (string) Required.
    • status (string) Required.
    • type (string) Required.

A string representing the ID of the newly created attendee record.

Available on Android only. Updates an existing attendee record. To remove a property, explicitly set it to null in details.

  • id (string) -- ID of the attendee record to be updated. Required.
  • details (object) --
    A map of properties to be updated (see below for a description of these fields):
    • id (string)
    • email (string)
    • name (string)
    • role (string)
    • status (string)
    • type (string)

Available on Android only. Deletes an existing attendee record from the device. Use with caution.

  • id (string) -- ID of the attendee to delete.

Available on iOS only. 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 -- i.e. all reminders that end after the startDate or begin before the endDate.

  • calendarIds (array) -- Array of IDs of calendars to search for reminders in. Required.
  • status (string) -- One of Calendar.ReminderStatus.COMPLETED or Calendar.ReminderStatus.INCOMPLETE.
  • startDate (Date) -- Beginning of time period to search for reminders in. Required if status is defined.
  • endDate (Date) -- End of time period to search for reminders in. Required if status is defined.

An array of reminder objects matching the search criteria.

Available on iOS only. Returns a specific reminder selected by ID.

  • id (string) -- ID of the reminder to return. Required.

An reminder object matching the provided ID, if one exists.

Available on iOS only. Creates a new reminder on the specified calendar.

  • calendarId (string) -- ID of the calendar to create this reminder in (or Expo.Calendar.DEFAULT to add the calendar to the OS-specified default calendar for reminders). Required.
  • details (object) --
    A map of details for the reminder to be created: (see below for a description of these fields)
    • title (string)
    • startDate (Date)
    • dueDate (Date)
    • completed (boolean)
    • completionDate (Date)
    • location (string)
    • notes (string)
    • alarms (array)
    • recurrenceRule (RecurrenceRule)
    • timeZone (string)
    • url (string)

A string representing the ID of the newly created reminder.

Available on iOS only. Updates the provided details of an existing reminder stored on the device. To remove a property, explicitly set it to null in details.

  • id (string) -- ID of the reminder to be updated. Required.
  • details (object) --
    A map of properties to be updated (see below for a description of these fields):
    • title (string)
    • startDate (Date)
    • dueDate (Date)
    • completionDate (Date) -- Setting this property of a nonnull Date will automatically set the reminder's completed value to true.
    • location (string)
    • notes (string)
    • alarms (array)
    • recurrenceRule (RecurrenceRule)
    • timeZone (string)
    • url (string)

Available on iOS only. Deletes an existing reminder from the device. Use with caution.

  • id (string) -- ID of the reminder to be deleted. Required.

Available on iOS only.

An array of source objects all sources for calendars stored on the device.

Available on iOS only. Returns a specific source selected by ID.

  • id (string) -- ID of the source to return. Required.

A source object matching the provided ID, if one exists.

Available on Android only. Sends an intent to open the specified event in the OS Calendar app.

  • id (string) -- ID of the event to open. Required.

A calendar record upon which events (or, on iOS, reminders) can be stored. Settings here apply to the calendar as a whole and how its events are displayed in the OS calendar app.
Field nameTypePlatformsDescriptionPossible values
idstringbothInternal ID that represents this calendar on the device
titlestringbothVisible name of the calendar
entityTypestringiOSWhether the calendar is used in the Calendar or Reminders OS appExpo.Calendar.EntityTypes.EVENT, Expo.Calendar.EntityTypes.REMINDER
sourceSourcebothObject representing the source to be used for the calendar
colorstringbothColor used to display this calendar's events
allowsModificationsbooleanbothBoolean value that determines whether this calendar can be modified
typestringiOSType of calendar this object representsExpo.Calendar.CalendarType.LOCAL, Expo.Calendar.CalendarType.CALDAV, Expo.Calendar.CalendarType.EXCHANGE, Expo.Calendar.CalendarType.SUBSCRIBED, Expo.Calendar.CalendarType.BIRTHDAYS
isPrimarybooleanAndroidBoolean value indicating whether this is the device's primary calendar
namestringAndroidInternal system name of the calendar
ownerAccountstringAndroidName for the account that owns this calendar
timeZonestringAndroidTime zone for the calendar
allowedAvailabilitiesarraybothAvailability types that this calendar supportsarray of Expo.Calendar.Availability.BUSY, Expo.Calendar.Availability.FREE, Expo.Calendar.Availability.TENTATIVE, Expo.Calendar.Availability.UNAVAILABLE (iOS only), Expo.Calendar.Availability.NOT_SUPPORTED (iOS only)
allowedRemindersarrayAndroidAlarm methods that this calendar supportsarray of Expo.Calendar.AlarmMethod.ALARM, Expo.Calendar.AlarmMethod.ALERT, Expo.Calendar.AlarmMethod.EMAIL, Expo.Calendar.AlarmMethod.SMS, Expo.Calendar.AlarmMethod.DEFAULT
allowedAttendeeTypesarrayAndroidAttendee types that this calendar supportsarray of Expo.Calendar.AttendeeType.UNKNOWN (iOS only), Expo.Calendar.AttendeeType.PERSON (iOS only), Expo.Calendar.AttendeeType.ROOM (iOS only), Expo.Calendar.AttendeeType.GROUP (iOS only), Expo.Calendar.AttendeeType.RESOURCE, Expo.Calendar.AttendeeType.OPTIONAL (Android only), Expo.Calendar.AttendeeType.REQUIRED (Android only), Expo.Calendar.AttendeeType.NONE (Android only)
isVisiblebooleanAndroidIndicates whether the OS displays events on this calendar
isSyncedbooleanAndroidIndicates whether this calendar is synced and its events stored on the device
accessLevelstringAndroidLevel of access that the user has for the calendarExpo.Calendar.CalendarAccessLevel.CONTRIBUTOR, Expo.Calendar.CalendarAccessLevel.EDITOR, Expo.Calendar.CalendarAccessLevel.FREEBUSY, Expo.Calendar.CalendarAccessLevel.OVERRIDE, Expo.Calendar.CalendarAccessLevel.OWNER, Expo.Calendar.CalendarAccessLevel.READ, Expo.Calendar.CalendarAccessLevel.RESPOND, Expo.Calendar.CalendarAccessLevel.ROOT, Expo.Calendar.CalendarAccessLevel.NONE

An event record, or a single instance of a recurring event. On iOS, used in the Calendar app.
Field nameTypePlatformsDescriptionPossible values
idstringbothInternal ID that represents this event on the device
calendarIdstringbothID of the calendar that contains this event
titlestringbothVisible name of the event
startDateDatebothDate object or string representing the time when the event starts
endDateDatebothDate object or string representing the time when the event ends
allDaybooleanbothWhether the event is displayed as an all-day event on the calendar
locationstringbothLocation field of the event
notesstringbothDescription or notes saved with the event
alarmsarraybothArray of Alarm objects which control automated reminders to the user
recurrenceRuleRecurrenceRulebothObject representing rules for recurring or repeating events. Null for one-time events.
availabilitystringbothThe availability setting for the eventExpo.Calendar.Availability.BUSY, Expo.Calendar.Availability.FREE, Expo.Calendar.Availability.TENTATIVE, Expo.Calendar.Availability.UNAVAILABLE (iOS only), Expo.Calendar.Availability.NOT_SUPPORTED (iOS only)
timeZonestringbothTime zone the event is scheduled in
endTimeZonestringAndroidTime zone for the event end time
urlstringiOSURL for the event
creationDatestringiOSDate when the event record was created
lastModifiedDatestringiOSDate when the event record was last modified
originalStartDatestringiOSFor recurring events, the start date for the first (original) instance of the event
isDetachedbooleaniOSBoolean value indicating whether or not the event is a detached (modified) instance of a recurring event
statusstringiOSStatus of the eventExpo.Calendar.EventStatus.NONE, Expo.Calendar.EventStatus.CONFIRMED, Expo.Calendar.EventStatus.TENTATIVE, Expo.Calendar.EventStatus.CANCELED
organizerAttendeeiOSOrganizer of the event, as an Attendee object
organizerEmailstringAndroidEmail address of the organizer of the event
accessLevelstringAndroidUser's access level for the eventExpo.Calendar.EventAccessLevel.CONFIDENTIAL, Expo.Calendar.EventAccessLevel.PRIVATE, Expo.Calendar.EventAccessLevel.PUBLIC, Expo.Calendar.EventAccessLevel.DEFAULT
guestsCanModifybooleanAndroidWhether invited guests can modify the details of the event
guestsCanInviteOthersbooleanAndroidWhether invited guests can invite other guests
guestsCanSeeGuestsbooleanAndroidWhether invited guests can see other guests
originalIdstringAndroidFor detached (modified) instances of recurring events, the ID of the original recurring event
instanceIdstringAndroidFor instances of recurring events, volatile ID representing this instance; not guaranteed to always refer to the same instance

A reminder record, used in the iOS Reminders app. No direct analog on Android.
Field nameTypeDescription
idstringInternal ID that represents this reminder on the device
calendarIdstringID of the calendar that contains this reminder
titlestringVisible name of the reminder
startDateDateDate object or string representing the start date of the reminder task
dueDateDateDate object or string representing the time when the reminder task is due
completedbooleanIndicates whether or not the task has been completed
completionDateDateDate object or string representing the date of completion, if completed is true
locationstringLocation field of the reminder
notesstringDescription or notes saved with the reminder
alarmsarrayArray of Alarm objects which control automated alarms to the user about the task
recurrenceRuleRecurrenceRuleObject representing rules for recurring or repeated reminders. Null for one-time tasks.
timeZonestringTime zone the reminder is scheduled in
urlstringURL for the reminder
creationDatestringDate when the reminder record was created
lastModifiedDatestringDate when the reminder record was last modified

A person or entity that is associated with an event by being invited or fulfilling some other role.
Field nameTypePlatformsDescriptionPossible values
idstringAndroidInternal ID that represents this attendee on the device
emailstringAndroidEmail address of the attendee
namestringbothDisplayed name of the attendee
rolestringbothRole of the attendee at the eventExpo.Calendar.AttendeeRole.UNKNOWN (iOS only), Expo.Calendar.AttendeeRole.REQUIRED (iOS only), Expo.Calendar.AttendeeRole.OPTIONAL (iOS only), Expo.Calendar.AttendeeRole.CHAIR (iOS only), Expo.Calendar.AttendeeRole.NON_PARTICIPANT (iOS only), Expo.Calendar.AttendeeRole.ATTENDEE (Android only), Expo.Calendar.AttendeeRole.ORGANIZER (Android only), Expo.Calendar.AttendeeRole.PERFORMER (Android only), Expo.Calendar.AttendeeRole.SPEAKER (Android only), Expo.Calendar.AttendeeRole.NONE (Android only)
statusstringbothStatus of the attendee in relation to the eventExpo.Calendar.AttendeeStatus.ACCEPTED, Expo.Calendar.AttendeeStatus.DECLINED, Expo.Calendar.AttendeeStatus.TENTATIVE, Expo.Calendar.AttendeeStatus.DELEGATED (iOS only), Expo.Calendar.AttendeeStatus.COMPLETED (iOS only), Expo.Calendar.AttendeeStatus.IN_PROCESS (iOS only), Expo.Calendar.AttendeeStatus.UNKNOWN (iOS only), Expo.Calendar.AttendeeStatus.PENDING (iOS only), Expo.Calendar.AttendeeStatus.INVITED (Android only), Expo.Calendar.AttendeeStatus.NONE (Android only)
typestringbothType of the attendeeExpo.Calendar.AttendeeType.UNKNOWN (iOS only), Expo.Calendar.AttendeeType.PERSON (iOS only), Expo.Calendar.AttendeeType.ROOM (iOS only), Expo.Calendar.AttendeeType.GROUP (iOS only), Expo.Calendar.AttendeeType.RESOURCE, Expo.Calendar.AttendeeType.OPTIONAL (Android only), Expo.Calendar.AttendeeType.REQUIRED (Android only), Expo.Calendar.AttendeeType.NONE (Android only)
urlstringiOSURL for the attendee
isCurrentUserbooleaniOSIndicates whether or not this attendee is the current OS user

A recurrence rule for events or reminders, allowing the same calendar item to recur multiple times.
Field nameTypeDescriptionPossible values
frequencystringHow often the calendar item should recurExpo.Calendar.Frequency.DAILY, Expo.Calendar.Frequency.WEEKLY, Expo.Calendar.Frequency.MONTHLY, Expo.Calendar.Frequency.YEARLY
intervalnumberInterval at which the calendar item should recur. For example, an interval: 2 with frequency: DAILY would yield an event that recurs every other day. Defaults to 1.
endDateDateDate on which the calendar item should stop recurring; overrides occurrence if both are specified
occurrencenumberNumber of times the calendar item should recur before stopping

A method for having the OS automatically remind the user about an calendar item
Field nameTypePlatformsDescriptionPossible values
absoluteDateDateiOSDate object or string representing an absolute time the alarm should occur; overrides relativeOffset and structuredLocation if specified alongside either
relativeOffsetnumberbothNumber of minutes from the startDate of the calendar item that the alarm should occur; use negative values to have the alarm occur before the startDate
methodstringAndroidMethod of alerting the user that this alarm should use; on iOS this is always a notificationExpo.Calendar.AlarmMethod.ALARM, Expo.Calendar.AlarmMethod.ALERT, Expo.Calendar.AlarmMethod.EMAIL, Expo.Calendar.AlarmMethod.SMS, Expo.Calendar.AlarmMethod.DEFAULT

A source account that owns a particular calendar. Expo apps will typically not need to interact with Source objects.
Field nameTypePlatformsDescriptionPossible values
idstringiOSInternal ID that represents this source on the device
namestringbothName for the account that owns this calendar
typestringbothType of account that owns this calendaron iOS, one of Expo.Calendar.SourceType.LOCAL, Expo.Calendar.SourceType.EXCHANGE, Expo.Calendar.SourceType.CALDAV, Expo.Calendar.SourceType.MOBILEME, Expo.Calendar.SourceType.SUBSCRIBED, or Expo.Calendar.SourceType.BIRTHDAYS
isLocalAccountbooleanAndroidWhether this source is the local phone account