The React Native Calendar Events module is great for giving your React Native apps access to the OS calendar and its events, as well as creating your own intricate events easily. If there was ever an amazing React-Native module that lacked opening documentation it would definitely be this one. For new users it is a trial-and-error process, but for such a great module I want to make sure that does not continue on. Let’s not only learn how to use react-native-calendar-events, but also see what it can do!
What it Does
Calendar Events gives you direct access to the OS Calendar with iOS and Android allowing your app to not only have access to the calendar events in any calendar, but also create new fully-featured events, and even edit existing events. Being able to create events themselves is by far an understatement of its power as you can also create a series of events with an alarm and set it to a specific calendar if you please.
With a limited amount of documentation it is hard to know what to expect let alone what to do. In our case it is best to know that output from this module is very minimal. In other words you are not going to see any sort of visual response from the module with simple examples regardless of it succeeding or failing. When I first started using it I thought it was linked to the calendar itself, bringing the calendar up after an event was created. While it does not do this it is not hard to make this happen.
Prepare for iOS 10
iOS 10 brought a lot of new features that made a lot of things change, and this is not any different with calendar events. If you attempt to run your as-is you will find that it will not even get past the loading screen. The reason being that iOS 10 added one more additional security measure before allowing access to the calendar.
To give your app this ability, you will need to add a new key to your project’s Info or Info.plist file.
Checking for and Getting Access to the Calendars
Starting out we want to make sure that the user authenticates access to the calendar(s). The best way to go about this is to set a state for the access status, check to see if we have access on startup, and then ask for access if we do not have access. You will want to do add this to your root application component, and pass the status down to the components that access the calendar. Keep in mind that if you blindly try to access the calendar limited output will be given, but you will find that none of your calendar components will work possibly causing some very odd side-effects.
Creating an Event and Showing That Event
here is a basic example of how to add an event to the calendar with a location, description, start/end date, set an alarm, all on a specific calendar.
The Location can be used in tandem with maps, so if you use a exact location (business/address, city, state, country), then you will find that calendars like the one in iOS will allow you to tap on the location and send you directly to the maps app.
You may notice that we have two very ambiguous options, notes, and description. Notes is used for the text in an iOS calendar event, where Description is specific to the description found in Android calendar events. This can be a good place to use a Platform.select to separate these two, but it’s not mandatory for this to work. In addition, for both iOS and Android to understand the time given, we need to make sure to convert to an ISOString. If you want you can also set these times manually with a string.
While I do not show how to use the function to check the available calendars, you can specify which calendars you want to add events to, in this case it is the default ‘Calendar‘ object. Lastly we see a Linking setup that actually opens the calendar after a successful response from the promise of saving the event. In this particular scenario you could take advantage of the newly saved event’s EventID to lookup the event using the findEventByID function, as the save method will return this value, the return value labeled id to be used immediately after creation.
While this barely scratches the surface of what you can do with the calendar events, you should be able to understand the rest of the API fairly easy after seeing these basics examples, something you cannot find in the docs. As you start to learn more, you will find that you have all of the ability needed to create your very own calendar application, viewing, creating, and editing events.
Now hit up the rest of the documentation to take advantage of the rest!
If you feel this documentation requires more to get started with calendar-events, or there are issues with the snippets, let me know in the comment below!