Use the CalendarService API

Add CalendarService to a Lightning Web Component

In your component’s JavaScript file, import CalendarService using the standard JavaScript import statement. Specifically, import the getCalendarService() factory function from the lightning/mobileCapabilities module, like so:

import { getCalendarService } from 'lightning/mobileCapabilities';

After it’s imported into your component, use the factory function to get an instance of CalendarService. With your CalendarService instance, use the utility functions and constants to verify availability. Then use calendar-related functions to perform the associated functionality.

Test CalendarService Availability

CalendarService depends on physical device hardware and platform features. A component that uses CalendarService renders without errors on a desktop computer or in a mobile browser, but calendar-related functions fail. To avoid these errors, test if CalendarService functionality is available before you use it.

handleManageCalendarEventsClick(event) {
   const myCalendarService = getCalendarService();
   if(myCalendarService.isAvailable()) {
     // Perform calendar-related operations
   }
   else {
     // CalendarService not available, or consuming app hasn’t implemented it 
     // Not running on hardware with a native calendar application, etc.
     // Handle with message, error, beep, and so on
   }
 }

Get Calendars

It’s simple to import device calendars into your Lightning web component using CalendarService. First, use getCalendars() to enable access within your component to available device calendars. Then, process the calendar data in whatever manner you wish.

For example:

// Get access to device calendars and process them
myCalendarService.getCalendars(options)
  .then((results) => {
    // do something with the calendar(s) data
    this.calendars = results;
    console.log(results);
  })
  .catch((error) => {
    // Handle cancellation or other errors here
    this.calendars = [];
    console.error('Error code: ' + error.code); +
    console.error('Error message: ' + error.message);
  });

Get Events

Fetch all calendar events within a specified date range with the getEvents() function. First, call the getEvents() function with the necessary parameters. Then, process or display event data in whatever manner you wish.

For example, if your calendar component has a “week view” and a “month view,” the startDateSecondsUTC and endDateSecondsUTC parameters need to be adjusted to capture the appropriate date range to be displayed. If you don’t want to display events from all mobile device calendars, specify the ones you want to work with in the calendars[] array.

For example:

// Get events from a specified date range on the specified calendar(s), and process them
myCalendarService.getEvents(startDateSecondsUTC, endDateSecondsUTC, calendars, options)
  .then((results) => {
    // Do something with the event(s) data
    this.events = results;
    console.log(results);
  })
  .catch((error) => {
    // Handle errors here
    this.events = [];
    console.error('Error code: ' + error.code); +
    console.error('Error message: ' + error.message);
  });

Create a Calendar Event

Create and add new calendar events to a mobile device with the addEvent() function. First, call the addEvent() function with the necessary parameters. Then, handle a successful outcome with a success message, or in any manner you wish. For more information on what the addEvent() function returns, see Implicit Data Coercion.

For example:

// Add an event to a mobile device calendar, and then handle a success
myCalendarService.addEvent(event, options)
  .then((results) => {
    // Do something with the event(s) data
    this.newEvent = results;
    console.log(results);
  })
  .catch((error) => {
    // Handle cancellation or other errors here
    console.error('Error code: ' + error.code); +
    console.error('Error message: ' + error.message);
  });

Update a Calendar Event

Update calendar events on a mobile device with the updateEvent() function. First, call the updateEvent() function with the necessary parameters. Then, handle a successful outcome with a success message, or in any manner you wish. For more information on what the updateEvent() function returns, see Implicit Data Coercion.

For example:

// Update an event on a mobile device calendar, and then handle a success
myCalendarService.updateEvent(event, options)
   .then((results) => {
     // Do something with the event(s) data
     this.updatedEvent = results;
     console.log(results);
   })
   .catch((error) => {
     // Handle cancellation or other errors here
     console.error('Error code: ' + error.code); +
     console.error('Error message: ' + error.message);
   });

Remove a Calendar Event

Remove calendar events on a mobile device with the removeEvent() function. First, call the removeEvent() function with the necessary parameters. Then, handle a successful outcome with a success message, or in any manner you wish.

For example:

// Remove an event on a mobile device calendar, and then handle a success
myCalendarService.removeEvent(event, options)
  .then((results) => {
    // Handle successful deletion here
    console.log('Event successfully deleted!');
  })
  .catch((error) => {
    // Handle cancellation or other errors here
    console.error('Error code: ' + error.code); +
    console.error('Error message: ' + error.message);
  });

Implicit Data Coercion

When passing in event data to a CalendarService function (namely the addEvent() and updateEvent() functions), CalendarService can change some event data before returning it. This behavior, referred to here as implicit data coercion, occurs when CalendarService adjusts the value of a property as a result of a user’s change of another property.

For example, if a new all-day event is added (or if an existing event is updated to be all-day) and a start time or end time is specified, CalendarService rejects the times. Instead, the start time is set to 00:00:00 (12:00:00 AM) and the end time to 23:59:59 (11:59:59 PM).

Implicit data coercion can also occur when changing details of recurring events. Any time recurring events are changed, their old IDs are overwritten and replaced with newly generated IDs.

Keep this in mind when using the addEvent() and updateEvent() functions. Your code should always use the coerced event data returned by CalendarService. Using raw (uncoerced) event data in your component can lead to errors and incorrect behavior.