Calendar

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

Platform Compatibility

Android Device	Android Emulator	iOS Device	iOS Simulator	Web

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.

Configuration

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.

Usage

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',
  },
});

API

import * as Calendar from 'expo-calendar';

Constants

`Calendar.AlarmMethod`

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

`Calendar.AttendeeRole`

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

`Calendar.AttendeeStatus`

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

`Calendar.AttendeeType`

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

`Calendar.Availability`

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

`Calendar.CalendarAccessLevel`

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

`Calendar.CalendarType`

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

`Calendar.EntityTypes`

Type: { EVENT: string, REMINDER: string }

`Calendar.EventAccessLevel`

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

`Calendar.EventStatus`

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

`Calendar.Frequency`

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

`Calendar.ReminderStatus`

Type: { COMPLETED: string, INCOMPLETE: string }

`Calendar.SourceType`

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

Hooks

`useCalendarPermissions`

Arguments

Name	Type	Description
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();

Name	Type	Description
eventId	`string`	ID of the event to add this attendee to.
details	`Partial<Attendee>`	A map of details for the attendee to be created.

Name	Type	Description
calendarId	`string`	ID of the calendar to create this event in.
eventData	`Partial<Event>`	A map of details for the event to be created.

Name	Type	Description
calendarId	`null \| string`	ID of the calendar to create this reminder in (or `null` to add the calendar to the OS-specified default calendar for reminders).
reminder	`Reminder`	A map of details for the reminder to be created

Name	Type	Description
id	`string`	ID of the event to be deleted.
recurringEventOptions	`RecurringEventOptions`	A map of options for recurring events.

Name	Type	Description
id	`string`	ID of the event to return attendees for.
recurringEventOptions	`RecurringEventOptions`	A map of options for recurring events.

Name	Type	Description
id	`string`	ID of the event to return.
recurringEventOptions	`RecurringEventOptions`	A map of options for recurring events.

Name	Type	Description
calendarIds	`string[]`	Array of IDs of calendars to search for events in.
startDate	`Date`	Beginning of time period to search for events in.
endDate	`Date`	End of time period to search for events in.

Name	Type	Description
calendarIds	`(null \| string)[]`	Array of IDs of calendars to search for reminders in.
status	`null \| 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.

Name	Type	Description
id	`string`	ID of the attendee record to be updated.
details	`Partial<Attendee>`	A map of properties to be updated.

Name	Type	Description
id	`string`	ID of the calendar to update.
details	`Partial<Calendar>`	A map of properties to be updated.

Name	Type	Description
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)	`number`	Number 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`	-

Name	Type	Description
coords (optional)	`{ latitude: number, longitude: number }`	-
proximity (optional)	`string`	-
radius (optional)	`number`	-
title (optional)	`string`	-

Name	Type	Description
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.
name	`string`	Displayed name of the attendee.
role	`string`	Role of the attendee at the event. Possible values: `AttendeeRole`.
status	`string`	Status of the attendee in relation to the event. Possible values: `AttendeeStatus`.
type	`string`	Type of the attendee. Possible values: `AttendeeType`.
url (optional)	`string`	iOS Only URL for the attendee.

Name	Type	Description
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`.
allowedAvailabilities	`string[]`	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`.
allowsModifications	`boolean`	Boolean value that determines whether this calendar can be modified.
color	`string`	Color 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`.
id	`string`	Internal 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.
source	`Source`	Object 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.
title	`string`	Visible name of the calendar.
type (optional)	`string`	iOS Only Type of calendar this object represents. Possible values: `CalendarType`.

Name	Type	Description
id	`string`	ID of the event to be updated.
details	`Partial<Event>`	A map of properties to be updated.
recurringEventOptions	`RecurringEventOptions`	A map of options for recurring events.

Name	Type	Description
id	`string`	ID of the reminder to be updated.
details	`Reminder`	A map of properties to be updated.

Name	Type	Description
dayOfTheWeek	`DayOfTheWeek`	Sunday 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).

Name	Type	Description
accessLevel (optional)	`string`	Android Only User's access level for the event. Possible values: `EventAccessLevel`.
alarms	`Alarm[]`	Array of Alarm objects which control automated reminders to the user.
allDay	`boolean`	Whether the event is displayed as an all-day event on the calendar
availability	`string`	The availability setting for the event. Possible values: `Availability`.
calendarId	`string`	ID of the calendar that contains this event.
creationDate (optional)	`string \| Date`	iOS Only Date when the event record was created.
endDate	`string \| Date`	Date 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.
id	`string`	Internal 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.
location	`string`	Location field of the event.
notes	`string`	Description 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.
recurrenceRule	`RecurrenceRule`	Object representing rules for recurring or repeating events. Set to `null` for one-time events.
startDate	`string \| Date`	Date object or string representing the time when the event starts.
status	`string`	Status of the event. Possible values: `EventStatus`.
timeZone	`string`	Time zone the event is scheduled in.
title	`string`	Visible name of the event.
url (optional)	`string`	iOS Only URL for the event.

Name	Type	Description
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 \| Date`	Date on which the calendar item should stop recurring; overrides `occurrence` if both are specified.
frequency	`string`	How often the calendar item should recur. Possible values: `Frequency`.
interval (optional)	`number`	Interval 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)	`number`	Number 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`.

Name	Type	Description
futureEvents (optional)	`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`.
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.

Name	Type	Description
alarms (optional)	`Alarm[]`	Array of Alarm objects which control automated alarms to the user about the task.
calendarId (optional)	`string`	ID of the calendar that contains this reminder.
completed (optional)	`boolean`	Indicates whether or not the task has been completed.
completionDate (optional)	`string \| Date`	Date 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 \| Date`	Date when the reminder record was created.
dueDate (optional)	`string \| Date`	Date object or string representing the time when the reminder task is due.
id (optional)	`string`	Internal ID that represents this reminder on the device.
lastModifiedDate (optional)	`string \| Date`	Date when the reminder record was last modified.
location (optional)	`string`	Location field of the reminder
notes (optional)	`string`	Description or notes saved with the reminder.
recurrenceRule (optional)	`RecurrenceRule`	Object representing rules for recurring or repeated reminders. Null for one-time tasks.
startDate (optional)	`string \| Date`	Date object or string representing the start date of the reminder task.
timeZone (optional)	`string`	Time zone the reminder is scheduled in.
title (optional)	`string`	Visible name of the reminder.
url (optional)	`string`	URL for the reminder.

Name	Type	Description
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`.
name	`string`	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. On iOS, one of `SourceType`s.

Name	Type	Description
canAskAgain	`boolean`	-
expires	`PermissionExpiration`	-
granted	`boolean`	-
status	`PermissionStatus`	-