React Native Calendar Events
A React Native module to help access and save events to iOS and Android calendars.
Table of contents
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 react-native-calendar-events
library with native code.
npm install --save react-native-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 theEventKit.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 'react-native-calendar-events';
authorizationStatus
Get calendar authorization status.
RNCalendarEvents.authorizationStatus()
Returns: Promise
- fulfilled: String -
denied
,restricted
,authorized
orundetermined
- 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
orundetermined
- 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
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: Date - The start date of the range of events fetched.
- endDate: Date - 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. - wiki guide
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. - wiki guide
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 | Date | The start date of the calendar event in ISO format. | ✓ | ✓ |
endDate | Date | 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* | Date | 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. | ✓ | ✓ |
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 | Date | 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 | Date or Number | If a Date 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 | Date | 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. |
✓ |
* Read only, ** Write only
Wiki
Authors
- Will McMahan - Initial code - github.com/wmcmahan
See also the list of contributors who participated in this project.
License
This project is licensed under the MIT License - see the LICENSE.md file for details
Acknowledgments
- Big thanks to all who have contributed, raised an issue or simply find use in this project. Cheers!