Docs-logo

Expo

Get Started
API Reference
Slash-shortcut-icon
Hamburger-icon

Calendar

Provides an API for interacting with the device's system calendars, events, reminders, and associated records.

Platform Compatibility

Android DeviceAndroid EmulatoriOS DeviceiOS SimulatorWeb
Status-success-iconStatus-success-iconStatus-success-iconStatus-success-iconStatus-failed-icon

Installation

Terminal
→ expo install expo-calendar

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

You must add the following permissions to your app.json.
  • Android requires READ_CALENDAR & WRITE_CALENDAR inside the expo.android.permissions array.
  • iOS requires the NSRemindersUsageDescription key be added to expo.ios.infoPlist with a string value describing the reason for the permission request.

import React, { useEffect } from 'react';
import { StyleSheet, View, Text, Button, Platform } from 'react-native';
import * as Calendar from 'expo-calendar';

export default function App() {
  useEffect(() => {
    (async () => {
      const { status } = await Calendar.requestCalendarPermissionsAsync();
      if (status === 'granted') {
        const calendars = await Calendar.getCalendarsAsync(Calendar.EntityTypes.EVENT);
        console.log('Here are all your calendars:');
        console.log({ calendars });
      }
    })();
  }, []);

  return (
    <View style={styles.container}>
      <Text>Calendar Module Example</Text>
      <Button title="Create a new calendar" onPress={createCalendar} />
    </View>
  );
}

async function getDefaultCalendarSource() {
  const defaultCalendar = await Calendar.getDefaultCalendarAsync();
  return defaultCalendar.source;
}

async function createCalendar() {
  const defaultCalendarSource =
    Platform.OS === 'ios'
      ? await getDefaultCalendarSource()
      : { isLocalAccount: true, name: 'Expo Calendar' };
  const newCalendarID = await Calendar.createCalendarAsync({
    title: 'Expo Calendar',
    color: 'blue',
    entityType: Calendar.EntityTypes.EVENT,
    sourceId: defaultCalendarSource.id,
    source: defaultCalendarSource,
    name: 'internalCalendarName',
    ownerAccount: 'personal',
    accessLevel: Calendar.CalendarAccessLevel.OWNER,
  });
  console.log(`Your new calendar ID is: ${newCalendarID}`);
}

%%placeholder-start%%const styles = StyleSheet.create({ ... }); %%placeholder-end%%const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#fff',
    alignItems: 'center',
    justifyContent: 'space-around',
  },
});

import * as Calendar from 'expo-calendar';

Type: { ALARM: string, ALERT: string, DEFAULT: string, EMAIL: string, SMS: string }

Type: { ATTENDEE: string, CHAIR: string, NONE: string, NON_PARTICIPANT: string, OPTIONAL: string, ORGANIZER: string, PERFORMER: string, REQUIRED: string, SPEAKER: string, UNKNOWN: string }

Type: { ACCEPTED: string, COMPLETED: string, DECLINED: string, DELEGATED: string, INVITED: string, IN_PROCESS: string, NONE: string, PENDING: string, TENTATIVE: string, UNKNOWN: string }

Type: { GROUP: string, NONE: string, OPTIONAL: string, PERSON: string, REQUIRED: string, RESOURCE: string, ROOM: string, UNKNOWN: string }

Type: { BUSY: string, FREE: string, NOT_SUPPORTED: string, TENTATIVE: string, UNAVAILABLE: string }

Type: { CONTRIBUTOR: string, EDITOR: string, FREEBUSY: string, NONE: string, OVERRIDE: string, OWNER: string, READ: string, RESPOND: string, ROOT: string }

Type: { BIRTHDAYS: string, CALDAV: string, EXCHANGE: string, LOCAL: string, SUBSCRIBED: string, UNKNOWN: string }

Type: { EVENT: string, REMINDER: string }

Type: { CONFIDENTIAL: string, DEFAULT: string, PRIVATE: string, PUBLIC: string }

Type: { CANCELED: string, CONFIRMED: string, NONE: string, TENTATIVE: string }

Type: { DAILY: string, MONTHLY: string, WEEKLY: string, YEARLY: string }

Type: { COMPLETED: string, INCOMPLETE: string }

Type: { BIRTHDAYS: string, CALDAV: string, EXCHANGE: string, LOCAL: string, MOBILEME: string, SUBSCRIBED: string }

Arguments

NameTypeDescription
options
(optional)
PermissionHookOptions<object>-

Check or request permissions to access the calendar. This uses both getCalendarPermissionsAsync and requestCalendarPermissionsAsync to interact with the permissions.

Example

const [status, requestPermission] = Calendar.useCalendarPermissions();

  • [null | PermissionResponse, RequestPermissionMethod<PermissionResponse>, GetPermissionMethod<PermissionResponse>]

Arguments

NameTypeDescription
options
(optional)
PermissionHookOptions<object>-

Check or request permissions to access reminders. This uses both getRemindersPermissionsAsync and requestRemindersPermissionsAsync to interact with the permissions.

Example

const [status, requestPermission] = Calendar.useRemindersPermissions();

Android Only

Arguments

NameTypeDescription
eventIdstringID of the event to add this attendee to.
detailsPartial<Attendee>A map of details for the attendee to be created.

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.

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


Arguments

NameTypeDescription
detailsPartial<Calendar>A map of details for the calendar to be created.

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

A string representing the ID of the newly created calendar.


Arguments

NameTypeDescription
calendarIdstringID of the calendar to create this event in.
eventDataPartial<Event>A map of details for the event to be created.

Creates a new event on the specified calendar.

A promise which fulfils with a string representing the ID of the newly created event.


iOS Only

Arguments

NameTypeDescription
calendarIdnull | stringID of the calendar to create this reminder in (or null to add the calendar to the OS-specified default calendar for reminders).
reminderReminderA map of details for the reminder to be created

Creates a new reminder on the specified calendar.

A promise which fulfils with a string representing the ID of the newly created reminder.


Android Only

Arguments

NameTypeDescription
idstringID of the attendee to delete.

Deletes an existing attendee record from the device. Use with caution.


Arguments

NameTypeDescription
idstringID of the calendar to delete.

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


Arguments

NameTypeDescription
idstringID of the event to be deleted.
recurringEventOptionsRecurringEventOptionsA map of options for recurring events.

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


iOS Only

Arguments

NameTypeDescription
idstringID of the reminder to be deleted.

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


Arguments

NameTypeDescription
idstringID of the event to return attendees for.
recurringEventOptionsRecurringEventOptionsA map of options for recurring events.

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

A promise which fulfils with an array of Attendee associated with the specified event.


Checks user's permissions for accessing user's calendars.

A promise that resolves to an object of type PermissionResponse.


Arguments

NameTypeDescription
entityType
(optional)
stringiOS Only. Not required, but if defined, filters the returned calendars to a specific entity type. Possible values are Calendar.EntityTypes.EVENT (for calendars shown in the Calendar app) and Calendar.EntityTypes.REMINDER (for the Reminders app). Note: if not defined, you will need both permissions: CALENDAR and REMINDERS.

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

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


iOS Only

Gets an instance of the default calendar object.

A promise resolving to the Calendar object that is the user's default calendar.


Arguments

NameTypeDescription
idstringID of the event to return.
recurringEventOptionsRecurringEventOptionsA map of options for recurring events.

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.

A promise which fulfils with an Event object matching the provided criteria, if one exists.


Arguments

NameTypeDescription
calendarIdsstring[]Array of IDs of calendars to search for events in.
startDateDateBeginning of time period to search for events in.
endDateDateEnd of time period to search for events in.

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.

A promise which fulfils with an array of Event objects matching the search criteria.


iOS Only

Arguments

NameTypeDescription
idstringID of the reminder to return.

Returns a specific reminder selected by ID.

A promise which fulfils with a Reminder matching the provided ID, if one exists.


iOS Only

Arguments

NameTypeDescription
calendarIds(null | string)[]Array of IDs of calendars to search for reminders in.
statusnull | stringOne of Calendar.ReminderStatus.COMPLETED or Calendar.ReminderStatus.INCOMPLETE.
startDateDateBeginning of time period to search for reminders in. Required if status is defined.
endDateDateEnd of time period to search for reminders in. Required if status is defined.

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.

A promise which fulfils with an array of Reminder objects matching the search criteria.


iOS Only

Checks user's permissions for accessing user's reminders.

A promise that resolves to an object of type PermissionResponse.


iOS Only

Arguments

NameTypeDescription
idstringID of the source to return.

Returns a specific source selected by ID.

A promise which fulfils with an array of Source object matching the provided ID, if one exists.


iOS Only

A promise which fulfils with an array of Source objects all sources for calendars stored on the device.


Returns whether the Calendar API is enabled on the current device. This does not check the app permissions.

Async boolean, indicating whether the Calendar API is available on the current device. Currently, this resolves true on iOS and Android only.


Android Only

Arguments

NameTypeDescription
idstringID of the event to open.

Sends an intent to open the specified event in the OS Calendar app.

  • void

Asks the user to grant permissions for accessing user's calendars.

A promise that resolves to an object of type PermissionResponse.


Info-icon
Deprecated. Use requestCalendarPermissionsAsync() instead.


iOS Only

Asks the user to grant permissions for accessing user's reminders.

A promise that resolves to an object of type PermissionResponse.


Android Only

Arguments

NameTypeDescription
idstringID of the attendee record to be updated.
detailsPartial<Attendee>A map of properties to be updated.

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


Arguments

NameTypeDescription
idstringID of the calendar to update.
detailsPartial<Calendar>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.


Arguments

NameTypeDescription
idstringID of the event to be updated.
detailsPartial<Event>A map of properties to be updated.
recurringEventOptionsRecurringEventOptionsA map of options for recurring events.

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


iOS Only

Arguments

NameTypeDescription
idstringID of the reminder to be updated.
detailsReminderA map of properties to be updated.

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

A method for having the OS automatically remind the user about an calendar item.

NameTypeDescription
absoluteDate
(optional)
string
iOS Only

Date object or string representing an absolute time the alarm should occur. Overrides relativeOffset and structuredLocation if specified alongside either.
method
(optional)
string
Android Only

Method of alerting the user that this alarm should use; on iOS this is always a notification. Possible values: AlarmMethod.
relativeOffset
(optional)
numberNumber 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.
structuredLocation
(optional)
AlarmLocation-

NameTypeDescription
coords
(optional)
{ latitude: number, longitude: number }-
proximity
(optional)
string-
radius
(optional)
number-
title
(optional)
string-

A person or entity that is associated with an event by being invited or fulfilling some other role.

NameTypeDescription
email
(optional)
string
Android Only

Email address of the attendee.
id
(optional)
string
Android Only

Internal ID that represents this attendee on the device.
isCurrentUser
(optional)
boolean
iOS Only

Indicates whether or not this attendee is the current OS user.
namestringDisplayed name of the attendee.
rolestringRole of the attendee at the event. Possible values: AttendeeRole.
statusstringStatus of the attendee in relation to the event. Possible values: AttendeeStatus.
typestringType of the attendee. Possible values: AttendeeType.
url
(optional)
string
iOS Only

URL for the attendee.

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.

NameTypeDescription
accessLevel
(optional)
string
Android Only

Level of access that the user has for the calendar. Possible values: CalendarAccessLevel.
allowedAttendeeTypes
(optional)
string[]
Android Only

Attendee types that this calendar supports. Possible values: Array of AttendeeType.
allowedAvailabilitiesstring[]Availability types that this calendar supports. Possible values: Array of Availability.
allowedReminders
(optional)
string[]
Android Only

Alarm methods that this calendar supports. Possible values: Array of AlarmMethod.
allowsModificationsbooleanBoolean value that determines whether this calendar can be modified.
colorstringColor used to display this calendar's events.
entityType
(optional)
string
iOS Only

Whether the calendar is used in the Calendar or Reminders OS app. Possible values: EntityTypes.
idstringInternal ID that represents this calendar on the device.
isPrimary
(optional)
boolean
Android Only

Boolean value indicating whether this is the device's primary calendar.
isSynced
(optional)
boolean
Android Only

Indicates whether this calendar is synced and its events stored on the device. Unexpected behavior may occur if this is not set to true.
isVisible
(optional)
boolean
Android Only

Indicates whether the OS displays events on this calendar.
name
(optional)
string | null
Android Only

Internal system name of the calendar.
ownerAccount
(optional)
string
Android Only

Name for the account that owns this calendar.
sourceSourceObject representing the source to be used for the calendar.
sourceId
(optional)
string
iOS Only

ID of the source to be used for the calendar. Likely the same as the source for any other locally stored calendars.
timeZone
(optional)
string
Android Only

Time zone for the calendar.
titlestringVisible name of the calendar.
type
(optional)
string
iOS Only

Type of calendar this object represents. Possible values: CalendarType.

iOS Only

NameTypeDescription
dayOfTheWeekDayOfTheWeekSunday to Saturday - DayOfTheWeek enum.
weekNumber
(optional)
number-53 to 53 (0 ignores this field, and a negative indicates a value from the end of the range).

An event record, or a single instance of a recurring event. On iOS, used in the Calendar app.

NameTypeDescription
accessLevel
(optional)
string
Android Only

User's access level for the event. Possible values: EventAccessLevel.
alarmsAlarm[]Array of Alarm objects which control automated reminders to the user.
allDaybooleanWhether the event is displayed as an all-day event on the calendar
availabilitystringThe availability setting for the event. Possible values: Availability.
calendarIdstringID of the calendar that contains this event.
creationDate
(optional)
string | Date
iOS Only

Date when the event record was created.
endDatestring | DateDate object or string representing the time when the event ends.
endTimeZone
(optional)
string
Android Only

Time zone for the event end time.
guestsCanInviteOthers
(optional)
boolean
Android Only

Whether invited guests can invite other guests.
guestsCanModify
(optional)
boolean
Android Only

Whether invited guests can modify the details of the event.
guestsCanSeeGuests
(optional)
boolean
Android Only

Whether invited guests can see other guests.
idstringInternal ID that represents this event on the device.
instanceId
(optional)
string
Android Only

For instances of recurring events, volatile ID representing this instance. Not guaranteed to always refer to the same instance.
isDetached
(optional)
boolean
iOS Only

Boolean value indicating whether or not the event is a detached (modified) instance of a recurring event.
lastModifiedDate
(optional)
string | Date
iOS Only

Date when the event record was last modified.
locationstringLocation field of the event.
notesstringDescription or notes saved with the event.
organizer
(optional)
string
iOS Only

Organizer of the event.
organizerEmail
(optional)
string
Android Only

Email address of the organizer of the event.
originalId
(optional)
string
Android Only

For detached (modified) instances of recurring events, the ID of the original recurring event.
originalStartDate
(optional)
string | Date
iOS Only

For recurring events, the start date for the first (original) instance of the event.
recurrenceRuleRecurrenceRuleObject representing rules for recurring or repeating events. Set to null for one-time events.
startDatestring | DateDate object or string representing the time when the event starts.
statusstringStatus of the event. Possible values: EventStatus.
timeZonestringTime zone the event is scheduled in.
titlestringVisible name of the event.
url
(optional)
string
iOS Only

URL for the event.

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 of the combinations make sense. For example, when frequency is DAILY, setting daysOfTheMonth makes no sense.

NameTypeDescription
daysOfTheMonth
(optional)
number[]
iOS Only

The days of the month this event occurs on. -31 to 31 (not including 0). Negative indicates a value from the end of the range. This field is only valid for Calendar.Frequency.Monthly.
daysOfTheWeek
(optional)
DaysOfTheWeek[]
iOS Only

The days of the week the event should recur on. An array of DaysOfTheWeek object.
daysOfTheYear
(optional)
number[]
iOS Only

The days of the year this event occurs on. -366 to 366 (not including 0). Negative indicates a value from the end of the range. This field is only valid for Calendar.Frequency.Yearly.
endDate
(optional)
string | DateDate on which the calendar item should stop recurring; overrides occurrence if both are specified.
frequencystringHow often the calendar item should recur. Possible values: Frequency.
interval
(optional)
numberInterval at which the calendar item should recur. For example, an interval: 2 with frequency: DAILY would yield an event that recurs every other day.

Default: 1
monthsOfTheYear
(optional)
MonthOfTheYear[]
iOS Only

The months this event occurs on. This field is only valid for Calendar.Frequency.Yearly.
occurrence
(optional)
numberNumber of times the calendar item should recur before stopping.
setPositions
(optional)
number[]
iOS Only

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. -366 to 366 (not including 0). Negative indicates a value from the end of the range. This field is only valid for Calendar.Frequency.Yearly.
weeksOfTheYear
(optional)
number[]
iOS Only

The weeks of the year this event occurs on. -53 to 53 (not including 0). Negative indicates a value from the end of the range. This field is only valid for Calendar.Frequency.Yearly.

iOS Only

NameTypeDescription
futureEvents
(optional)
booleanWhether 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.
instanceStartDate
(optional)
string | DateDate 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.

iOS Only

A reminder record, used in the iOS Reminders app. No direct analog on Android.

NameTypeDescription
alarms
(optional)
Alarm[]Array of Alarm objects which control automated alarms to the user about the task.
calendarId
(optional)
stringID of the calendar that contains this reminder.
completed
(optional)
booleanIndicates whether or not the task has been completed.
completionDate
(optional)
string | DateDate 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.
creationDate
(optional)
string | DateDate when the reminder record was created.
dueDate
(optional)
string | DateDate object or string representing the time when the reminder task is due.
id
(optional)
stringInternal ID that represents this reminder on the device.
lastModifiedDate
(optional)
string | DateDate when the reminder record was last modified.
location
(optional)
stringLocation field of the reminder
notes
(optional)
stringDescription or notes saved with the reminder.
recurrenceRule
(optional)
RecurrenceRuleObject representing rules for recurring or repeated reminders. Null for one-time tasks.
startDate
(optional)
string | DateDate object or string representing the start date of the reminder task.
timeZone
(optional)
stringTime zone the reminder is scheduled in.
title
(optional)
stringVisible name of the reminder.
url
(optional)
stringURL for the reminder.

A source account that owns a particular calendar. Expo apps will typically not need to interact with Source objects.

NameTypeDescription
id
(optional)
string
iOS Only

Internal ID that represents this source on the device.
isLocalAccount
(optional)
boolean
Android Only

Whether this source is the local phone account. Must be true if type is undefined.
namestringName for the account that owns this calendar and was used to sync the calendar to the device.
typestringType 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. On iOS, one of SourceTypes.

NameTypeDescription
canAskAgainboolean-
expiresPermissionExpiration-
grantedboolean-
statusPermissionStatus-

  • Sunday

    DayOfTheWeek.Sunday1

  • Monday

    DayOfTheWeek.Monday2

  • Tuesday

    DayOfTheWeek.Tuesday3

  • Wednesday

    DayOfTheWeek.Wednesday4

  • Thursday

    DayOfTheWeek.Thursday5

  • Friday

    DayOfTheWeek.Friday6

  • Saturday

    DayOfTheWeek.Saturday7

  • January

    MonthOfTheYear.January1

  • February

    MonthOfTheYear.February2

  • March

    MonthOfTheYear.March3

  • April

    MonthOfTheYear.April4

  • May

    MonthOfTheYear.May5

  • June

    MonthOfTheYear.June6

  • July

    MonthOfTheYear.July7

  • August

    MonthOfTheYear.August8

  • September

    MonthOfTheYear.September9

  • October

    MonthOfTheYear.October10

  • November

    MonthOfTheYear.November11

  • December

    MonthOfTheYear.December12

  • DENIED

    PermissionStatus.DENIED"denied"

  • GRANTED

    PermissionStatus.GRANTED"granted"

  • UNDETERMINED

    PermissionStatus.UNDETERMINED"undetermined"