Repository files navigation

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

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 withReact Native.

For 0.59-, you should usejetify -r

$ npm install --save react-native-calendar-events# --- or ---$ yarn add react-native-calendar-events

Don't forget going into theios directory to execute apod install.

Because this package targets React Native 0.60.0+, you will probably don't need to link it manually. Otherwise if it's not the case, follow this additional instructions:

target'YourAwesomeProject'do# …  pod'RNCalendarEvents', :path =>'../node_modules/react-native-calendar-events'end

include':react-native-calendar-events'project(':react-native-calendar-events').projectDir=newFile(rootProject.projectDir,'../node_modules/react-native-calendar-events/android')

dependencies {// ...  implementation project(':react-native-calendar-events')}

importcom.calendarevents.RNCalendarEventsPackage;// <- add the RNCalendarEventsPackage importpublicclassMainApplicationextendsApplicationimplementsReactApplication {// …@OverrideprotectedList<ReactPackage>getPackages() {@SuppressWarnings("UnnecessaryLocalVariable")List<ReactPackage>packages =newPackageList(this).getPackages();// …packages.add(newRNCalendarEventsPackage());returnpackages;  }// …}

AddRNCalendarEvents, as well asEventKit.framework to project libraries if not already done.

Setting up privacy usage descriptions may also be required depending on which iOS version is supported. This involves updating the Property List,Info.plist, with the corresponding key for the EKEventStore api.Info.plist reference.

For updating theInfo.plist key/value via XCode, add aPrivacy - Calendars Usage Description key with a usage description as the value. Resulting change toInfo.plist should look something like:

<key>NSCalendarsUsageDescription</key><string>This app requires access to the calendar</string>

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

importRNCalendarEventsfrom"react-native-calendar-events";

Get calendar authorization status.You may check for the default read/write access with no argument, or read-only access on Android by passing boolean true. iOS is always read/write.

RNCalendarEvents.checkPermissions((readOnly=false));

Returns:Promise

• fulfilled: String -denied,restricted,authorized orundetermined
• rejected: Error

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

RNCalendarEvents.requestPermissions((readOnly=false));

(readOnly is for Android only, see below)

Android note: this is necessary for targeted SDK of >=23.iOS note: This method will crash, if you didn't updateInfo.plist. Follow carefully installation instruction.

Returns:Promise

• fulfilled: String -denied,restricted,authorized orundetermined
• rejected: Error

⚠️ Note that to restrict to read-only usage on Android (iOS is always read/write) you will need to alter the included Android permissionsas theAndroidManifest.xml is merged during the Android build.

You do that by altering your AndroidManifest.xml to "remove" the WRITE_CALENDAR permission with an entry like so:

<manifestxmlns:android="http://schemas.android.com/apk/res/android"xmlns:tools="http://schemas.android.com/tools"  ><!-- ...-->  <uses-permissiontools:node="remove"android:name="android.permission.WRITE_CALENDAR" />

Finds all the calendars on the device.

RNCalendarEvents.findCalendars();

Returns:Promise

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

Create a calendar.

RNCalendarEvents.saveCalendar(calendar);

⚠️ When you want to save a calendar, you need to use a valid source (find usingfindCalendars).

Arguments:

• calendar: Object - Calendar to create.

Returns:Promise

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

Removes a calendar.

RNCalendarEvents.removeCalendar(id);

Arguments:

• id: String - The id of the calendar to remove.

Returns:Promise

• fulfilled: Bool - Successful
• rejected: Error

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

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

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. Note that on Android,saveEvent accepts an additional optionsync (boolean) to prevent syncing issues.

Returns:Promise

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

To update an event, the eventid must be defined. -wiki guide

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

Creating events is fairly straightforward. Hopefully the following explanation can help.

For both iOS and Android the pattern is simple; the event needs atitle as well as astartDate andendDate. TheendDate should also be a date later than thestartDate.

RNCalendarEvents.saveEvent('Title of event',{startDate:'2016-08-19T19:26:00.000Z',endDate:'2017-08-19T19:26:00.000Z'})

The example above will simply save the event to your devices default calendar. If you wish to control which calendar the event is saved to, you must provide thecalendarId. This will ensure your event is saved to an expected calendar.

RNCalendarEvents.saveEvent('Title of event',{calendarId:'141',startDate:'2016-08-19T19:26:00.000Z',endDate:'2017-08-19T19:26:00.000Z'})

There are also other writable fields available. For example, you may wish to specify the location of the event or add additional notes for the event. Complete list of fields can be foundin the wiki.

RNCalendarEvents.saveEvent('Title of event',{calendarId:'141',startDate:'2016-08-19T19:26:00.000Z',endDate:'2017-08-19T19:26:00.000Z',location:'Los Angeles, CA',notes:'Bring sunglasses'})

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

*Read only, ** _Write only

These are some common issues you may run into while usingreact-native-calendar-events library.If you encounter something that is not listed here, trysearching in GitHub issues ofreact-native-calendar-events.

This might be related to a sync issue.You need to be sure that the event you saved is matching what your device will keep in sync.

For iOS, you might have not all event synced. You might need to update this iOS settings inSettings >Calendar >Sync >All Events. If that's not enough, it might be worth checkingiOS iCloud sync documentation.
For Android, you can have a look toGoogle Calendar sync problems documentation.

Another symptom of syncing issue. See the issue above.Note that on Android,saveEvent accepts an additional optionsync (boolean) to prevent syncing issues.

• Create basic event
• Create recurring event
• Updating events
• Adding alarms

• Will McMahan - Initial code -github.com/wmcmahan

See also the list ofcontributors who participated in this project.

This project is licensed under the MIT License - see theLICENSE.md file for details

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