React Native Calendar Events

A React Native module to help access and save events to iOS and Android calendars.

Table of contents

• Getting started
  • Install
  • Link the library
  • OS specific setup
• API methods
  • authorizationStatus
  • authorizeEventStore
  • findCalendars
  • saveCalendar
  • findEventById
  • fetchAllEvents
  • saveEvent
  • removeEvent
• Event fields
  • Recurrence rules
  • Alarm
  • Alarm structuredLocation
  • Options
• Calendar

Getting started

This package assumes that you already have a React Native project or are familiar with React Native. If not, checkout the official documentation for more details about getting started with React Native.

The following is required for the package to work properly.

Step 1. - Install

Install the rn-calendar-events library with native code.

npm install --save rn-calendar-events

Step 2. - Link the library

Since this package contains native code, you will need to include the code as a library. The React Native documentation on "Linking Libraries" also provides some details for this process.

• Automatic linking

react-native link

• Manual linking Sometimes "automatic linking" is not sufficient or is not properly including the library. Fortunately, the React Native docs on "Manual Linking" serves a helpful guide (with pictures) in the process.

Step 3. - OS specific setup

• [iOS specific instructions] iOS specific requirements, such as mandatory privacy usage descriptions and including the EventKit.framework.

• [Android specific instructions] Android specific requirements, such as mandatory application permissions.

API

The following API allows for interacting with both iOS and Android device calendars. See the full list of available event fields.

import RNCalendarEvents from 'rn-calendar-events';

authorizationStatus

Get calendar authorization status.

RNCalendarEvents.authorizationStatus()

Returns: Promise

• fulfilled: String - denied, restricted, authorized or undetermined
• rejected: Error

authorizeEventStore

Request calendar authorization. Authorization must be granted before accessing calendar events.

Android note: This is only necessary for targeted SDK of 23 and higher.

RNCalendarEvents.authorizeEventStore()

Returns: Promise

• fulfilled: String - denied, restricted, authorized or undetermined
• rejected: Error

findCalendars

Finds all the calendars on the device.

RNCalendarEvents.findCalendars()

Returns: Promise

• fulfilled: Array - A list of known calendars on the device
• rejected: Error

saveCalendar

Create a calendar.

RNCalendarEvents.saveCalendar(calendar)

Arguments:

• calendar: Object - Calendar to create.

Returns: Promise

• fulfilled: The id of the created calendar
• rejected: Error

findEventById

Find calendar event by id. Returns a promise with fulfilled found events.

RNCalendarEvents.findEventById(id)

Arguments:

• id: String - The events unique id.

Returns: Promise

• fulfilled: Object | null - Found event with unique id.
• rejected: Error

fetchAllEvents

Fetch all calendar events. Returns a promise with fulfilled found events.

RNCalendarEvents.fetchAllEvents(startDate, endDate, calendars)

Arguments:

• startDate: String - The start date of the range of events fetched.
• endDate: String - The end date of the range of events fetched.
• calendars: Array - List of calendar id strings to specify calendar events. Defaults to all calendars if empty.

Returns: Promise

• fulfilled: Array - Matched events within the specified date range.
• rejected: Error

saveEvent

Creates or updates a calendar event.

RNCalendarEvents.saveEvent(title, details, options);

Arguments:

• title: String - The title of the event.
• details: Object - The event's details.
• options: Object - Options specific to the saved event.

Returns: Promise

• fulfilled: String - Created event's ID.
• rejected: Error

To update an event, the event id must be defined.

RNCalendarEvents.saveEvent(title, {id: 'FE6B128F-C0D8-4FB8-8FC6-D1D6BA015CDE'})

removeEvent

Removes calendar event.

RNCalendarEvents.removeEvent(id, options)

Arguments:

• id: String - The id of the event to remove.
• options: Object - Options specific to event removal.

Returns: Promise

• fulfilled: Bool - Successful
• rejected: Error

Event fields

| Property | Type | Description | iOS | Android | | :--------------- | :---------------- | :----------- | :-----------: | :-----------: | | id* | String | Unique id for the calendar event. | ✓ | ✓ | | calendarId** | String | Unique id for the calendar where the event will be saved. Defaults to the device's default calendar. | ✓ | ✓ | | title | String | The title for the calendar event. | ✓ | ✓ | | startDate | String | The start date of the calendar event in ISO format. | ✓ | ✓ | | endDate | String | The end date of the calendar event in ISO format. | ✓ | ✓ | | allDay | Bool | Indicates whether the event is an all-day event. | ✓ | ✓ | | recurrence | String | The simple recurrence frequency of the calendar event daily, weekly, monthly, yearly or none. | ✓ | ✓ | | recurrenceRule ** | Object | The events recurrence settings. | ✓ | ✓ | | occurrenceDate* | String | The original occurrence date of an event if it is part of a recurring series. | ✓ | | | isDetached | Bool | Indicates whether an event is a detached instance of a repeating event. | ✓ | | | url | String | The url associated with the calendar event. | ✓ | | | location | String | The location associated with the calendar event. | ✓ | ✓ | | notes | String | The notes associated with the calendar event. | ✓ | | | description | String | The description associated with the calendar event. | | ✓ | | alarms | Array | The alarms associated with the calendar event, as an array of alarm objects. | ✓ | ✓ | | attendees* | Array | The attendees of the event, including the organizer. | ✓ | ✓ | | calendar* | Object | The calendar containing the event.| ✓ | ✓ | | skipAndroidTimezone | Bool | Skip the process of setting automatic timezone on android| | ✓ |

Calendar

| Property | Type | Description | iOS | Android | | :--------------- | :---------------- | :----------- | :-----------: | :-----------: | | id | String | Unique calendar ID. | ✓ | ✓ | | title | String | The calendar’s title. | ✓ | ✓ | | type | String | The calendar’s type. | ✓ | ✓ | | source | String | The source object representing the account to which this calendar belongs. | ✓ | ✓ | | isPrimary* | Bool | Indicates if the calendar is assigned as primary. | ✓ | ✓ | | allowsModifications* | Bool | Indicates if the calendar allows events to be written, edited or removed. | ✓ | ✓ | | color* | String | The color assigned to the calendar represented as a hex value. | ✓ | ✓ | | allowedAvailabilities* | Array | The event availability settings supported by the calendar. | ✓ | ✓ |

Attendees

| Property | Type | Description | iOS | Android | | :--------------- | :---------------- | :----------- | :-----------: | :-----------: | | name | String | The name of the attendee. | ✓ | ✓ | | email* | String | The email address of the attendee. | ✓ | ✓ | | phone* | String | The phone number of the attendee. | ✓ | |

Recurrence rule

| Property | Type | Description | iOS | Android | | :--------------- | :---------------- | :----------- | :-----------: | :-----------: | | frequency | String | Event recurring frequency. Allowed values are daily, weekly, monthly, yearly. | ✓ | ✓ | | endDate | String | Event recurring end date. This overrides occurrence. | ✓ | ✓ | | occurrence | Number | Number of event occurrences. | ✓ | ✓ | | interval | Number | The interval between events of this recurrence. | ✓ | ✓ |

Alarms

| Property | Type | Description | iOS | Android | | :--------------- | :------------------| :----------- | :-----------: | :-----------: | | date | String or Number | If a String is given, an alarm will be set with an absolute date. If a Number is given, an alarm will be set with a relative offset (in minutes) from the start date. | ✓ | ✓ | | structuredLocation | Object | The location to trigger an alarm. | ✓ | |

Alarm structuredLocation

| Property | Type | Description | iOS | Android | | :--------------- | :------------------| :----------- | :-----------: | :-----------: | | title | String | The title of the location.| ✓ | | | proximity | String | A value indicating how a location-based alarm is triggered. Possible values: enter, leave, none. | ✓ | | | radius | Number | A minimum distance from the core location that would trigger the calendar event's alarm. | ✓ | | | coords | Object | The geolocation coordinates, as an object with latitude and longitude properties | ✓ | |

Options

| Property | Type | Description | iOS | Android | | :--------------- | :---------------- | :----------- | :-----------: | :-----------: | | exceptionDate | String | The start date of a recurring event's exception instance. Used for updating single event in a recurring series | ✓ | ✓ | | futureEvents | Bool | If true the update will span all future events. If false it only update the single instance. | ✓ | |

Calendar options

| Property | Type | Description | iOS | Android | | :--------------- | :---------------- | :----------- | :-----------: | :-----------: | | title | String | The calendar title (required) | ✓ | ✓ | | color | String | The calendar color (required) | ✓ | ✓ | | entityType | String | 'event' or 'reminder' (required) | ✓ | | | name | String | The calendar name (required) | | ✓ | | accessLevel | String | Defines how the event shows up for others when the calendar is shared doc(required) 'contributor', 'editor', 'freebusy', 'override', 'owner', 'read', 'respond', 'root' | | ✓ | | ownerAccount | String | The owner account for this calendar, based on the calendar feed doc(required) | | ✓ | | source | Object | The calendar Account source (required) | | ✓ | | source.name | String | The Account name (required) | | ✓ | | source.type | String | The Account type | | ✓ | | source.isLocalAccount | Bool | The source (required if source.type is not used)| | ✓ |

License

This project is licensed under the MIT License.

Acknowledgments

• Big thanks to all who have contributed, raised an issue or simply find use in this project. Cheers!