Class ICalEvent

Constructor of [[ICalEvent]. The calendar reference is required to query the calendar's timezone when required.

Get all alarms

Add one or multiple alarms

const event = ical().createEvent();

cal.alarms([
    {type: ICalAlarmType.display, trigger: 600},
    {type: ICalAlarmType.audio, trigger: 300}
]);

cal.alarms(); // --> [ICalAlarm, ICalAlarm]
Copy

Get the event's allDay flag

Set the event's allDay flag.

event.allDay(true); // → appointment is for the whole day
Copy

import ical from 'ical-generator';

const cal = ical();

cal.createEvent({
  start: new Date('2020-01-01'),
  summary: 'Very Important Day',
  allDay: true
});

cal.toString();
Copy

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//sebbo.net//ical-generator//EN
BEGIN:VEVENT
UID:1964fe8d-32c5-4f2a-bd62-7d9d7de5992b
SEQUENCE:0
DTSTAMP:20240212T191956Z
DTSTART;VALUE=DATE:20200101
X-MICROSOFT-CDO-ALLDAYEVENT:TRUE
X-MICROSOFT-MSNCALENDAR-ALLDAYEVENT:TRUE
SUMMARY:Very Important Day
END:VEVENT
END:VCALENDAR
Copy

Get all attachment urls

Add one or multiple alarms

const event = ical().createEvent();

cal.attachments([
    'https://files.sebbo.net/calendar/attachments/foo',
    'https://files.sebbo.net/calendar/attachments/bar'
]);

cal.attachments(); // --> [string, string]
Copy

3.2.0-develop.1

Get all attendees

Add multiple attendees to your event

const event = ical().createEvent();

cal.attendees([
    {email: 'a@example.com', name: 'Person A'},
    {email: 'b@example.com', name: 'Person B'}
]);

cal.attendees(); // --> [ICalAttendee, ICalAttendee]
Copy

Get the event's busy status

Set the event's busy status. Will add the X-MICROSOFT-CDO-BUSYSTATUS attribute to your event.

import ical, {ICalEventBusyStatus} from 'ical-generator';
event.busystatus(ICalEventBusyStatus.BUSY);
Copy

Get all categories

Add categories to the event or return all selected categories.

const event = ical().createEvent();

cal.categories([
    {name: 'APPOINTMENT'},
    {name: 'MEETING'}
]);

cal.categories(); // --> [ICalCategory, ICalCategory]
Copy

Get the event's class

Set the event's class

import ical, { ICalEventClass } from 'ical-generator';
event.class(ICalEventClass.PRIVATE);
Copy

Creates a new ICalAlarm and returns it. Use options to prefill the alarm's attributes. Calling this method without options will create an empty alarm.

const cal = ical();
const event = cal.createEvent();
const alarm = event.createAlarm({type: ICalAlarmType.display, trigger: 300});

// add another alarm
event.createAlarm({
    type: ICalAlarmType.audio,
    trigger: 300, // 5min before event
});
Copy

Adds an attachment to the event by adding the file URL to the calendar.

ical-generator only supports external attachments. File attachments that are directly included in the file are not supported, because otherwise the calendar file could easily become unfavourably large.

const cal = ical();
const event = cal.createEvent();
event.createAttachment('https://files.sebbo.net/calendar/attachments/foo');
Copy

Creates a new ICalAttendee and returns it. Use options to prefill the attendee's attributes. Calling this method without options will create an empty attendee.

import ical from 'ical-generator';

const cal = ical();
const event = cal.createEvent({
  start: new Date()
});

event.createAttendee({email: 'hui@example.com', name: 'Hui'});

// add another attendee
event.createAttendee('Buh <buh@example.net>');
Copy

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//sebbo.net//ical-generator//EN
BEGIN:VEVENT
UID:b4944f07-98e4-4581-ac80-2589bb20273d
SEQUENCE:0
DTSTAMP:20240212T194232Z
DTSTART:20240212T194232Z
SUMMARY:
ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Hui":MAILTO:hui@example.com
ATTENDEE;ROLE=REQ-PARTICIPANT;CN="Buh":MAILTO:buh@example.net
END:VEVENT
END:VCALENDAR
Copy

As with the organizer, you can also add an explicit mailto address.

event.createAttendee({email: 'hui@example.com', name: 'Hui', mailto: 'another@mailto.com'});

// overwrite an attendee's mailto address
attendee.mailto('another@mailto.net');
Copy

Creates a new ICalCategory and returns it. Use options to prefill the category's attributes. Calling this method without options will create an empty category.

const cal = ical();
const event = cal.createEvent();
const category = event.createCategory({name: 'APPOINTMENT'});

// add another category
event.createCategory({
    name: 'MEETING'
});
Copy

Get the event's creation date

Set the event's creation date

Get the event's description as an ICalDescription object.

Set the events description by passing a plaintext string or an object containing both a plaintext and a html description. Only a few calendar apps support html descriptions and like in emails, supported HTML tags and styling is limited.

event.description({
    plain: 'Hello World!',
    html: '<p>Hello World!</p>'
});
Copy

DESCRIPTION:Hello World!
X-ALT-DESC;FMTTYPE=text/html:<p>Hello World!</p>
Copy

Get the event end time which is currently set. Can be any supported date object.

Set the appointment date of end. You can use any supported date object, see readme for details about supported values and timezone handling.

Get the event's floating flag.

Get the event's ID

Use this method to set the event's ID. If not set, a UUID will be generated randomly.

Get the event's last modification date

Set the event's last modification date

Get the event's location

Set the event's location by passing a string (minimum) or an ICalLocationWithTitle object which will also fill the iCal GEO attribute and Apple's X-APPLE-STRUCTURED-LOCATION.

event.location({
   title: 'Apple Store Kurfürstendamm',
   address: 'Kurfürstendamm 26, 10719 Berlin, Deutschland',
   radius: 141.1751386318387,
   geo: {
       lat: 52.503630,
       lon: 13.328650
   }
});
Copy

LOCATION:Apple Store Kurfürstendamm\nKurfürstendamm 26\, 10719 Berlin\,
 Deutschland
X-APPLE-STRUCTURED-LOCATION;VALUE=URI;X-ADDRESS=Kurfürstendamm 26\, 10719
  Berlin\, Deutschland;X-APPLE-RADIUS=141.1751386318387;X-TITLE=Apple Store
  Kurfürstendamm:geo:52.50363,13.32865
GEO:52.50363;13.32865
Copy

Since v6.1.0 you can also pass a ICalLocationWithoutTitle object to pass the geolocation only. This will only fill the iCal GEO attribute.

event.location({
   geo: {
       lat: 52.503630,
       lon: 13.328650
   }
});
Copy

GEO:52.50363;13.32865
Copy

Get the event's organizer

Set the event's organizer

event.organizer({
   name: 'Organizer\'s Name',
   email: 'organizer@example.com'
});

// OR

event.organizer('Organizer\'s Name <organizer@example.com>');
Copy

You can also add an explicit mailto email address or or the sentBy address.

    event.organizer({
   name: 'Organizer\'s Name',
   email: 'organizer@example.com',
   mailto: 'explicit@mailto.com',
   sentBy: 'substitute@example.com'
})
Copy

Get the event's priority. A value of 1 represents the highest priority, 9 the lowest. 0 specifies an undefined priority.

Set the event's priority. A value of 1 represents the highest priority, 9 the lowest. 0 specifies an undefined priority.

Get the event's recurrence id

Set the event's recurrence id. You can use any supported date object, see readme for details about supported values and timezone handling.

Get the event's repeating options

Set the event's repeating options by passing an ICalRepeatingOptions object.

event.repeating({
   freq: 'MONTHLY', // required
   count: 5,
   interval: 2,
   until: new Date('Jan 01 2014 00:00:00 UTC'),
   byDay: ['su', 'mo'], // repeat only sunday and monday
   byMonth: [1, 2], // repeat only in january and february,
   byMonthDay: [1, 15], // repeat only on the 1st and 15th
   bySetPos: 3, // repeat every 3rd sunday (will take the first element of the byDay array)
   exclude: [new Date('Dec 25 2013 00:00:00 UTC')], // exclude these dates
   excludeTimezone: 'Europe/Berlin', // timezone of exclude
   wkst: 'SU' // Start the week on Sunday, default is Monday
});
Copy

Example:

import ical, { ICalEventRepeatingFreq } from 'ical-generator';

const cal = ical();

const event = cal.createEvent({
  start: new Date('2020-01-01T20:00:00Z'),
  summary: 'Repeating Event'
});
event.repeating({
  freq: ICalEventRepeatingFreq.WEEKLY,
  count: 4
});

cal.toString();
Copy

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//sebbo.net//ical-generator//EN
BEGIN:VEVENT
UID:b80e6a68-c2cd-48f5-b94d-cecc7ce83871
SEQUENCE:0
DTSTAMP:20240212T193646Z
DTSTART:20200101T200000Z
RRULE:FREQ=WEEKLY;COUNT=4
SUMMARY:Repeating Event
END:VEVENT
END:VCALENDAR
Copy

Set the event's repeating options by passing an RRule object.

Set the events repeating options by passing a string which is inserted in the ical file.

Get the event's SEQUENCE number. Use this method to get the event's revision sequence number of the calendar component within a sequence of revisions.

Set the event's SEQUENCE number. For a new event, this should be zero. Each time the organizer makes a significant revision, the sequence number should be incremented.

Get the event's timestamp

Set the appointment date of creation. Defaults to the current time and date (new Date()). You can use any supported date object, see readme for details about supported values and timezone handling.

Get the event start time which is currently set. Can be any supported date object.

Set the appointment date of beginning, which is required for all events. You can use any supported date object, see Readme for details about supported values and timezone handling.

import ical from 'ical-generator';

const cal = ical();

const event = cal.createEvent({
  start: new Date('2020-01-01')
});

// overwrites old start date
event.start(new Date('2024-02-01'));

cal.toString();
Copy

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//sebbo.net//ical-generator//EN
BEGIN:VEVENT
UID:7e2aee64-b07a-4256-9b3e-e9eaa452bac8
SEQUENCE:0
DTSTAMP:20240212T190915Z
DTSTART:20240201T000000Z
SUMMARY:
END:VEVENT
END:VCALENDAR
Copy

Get the event's status

Set the event's status

import ical, {ICalEventStatus} from 'ical-generator';
event.status(ICalEventStatus.CONFIRMED);
Copy

Get the event's summary

Set the event's summary. Defaults to an empty string if nothing is set.

Get the event's timestamp

Set the appointment date of creation. Defaults to the current time and date (new Date()). You can use any supported date object, see readme for details about supported values and timezone handling.

Get the event's timezone.

Sets the time zone to be used for this event. If a time zone has been defined in both the event and the calendar, the time zone of the event is used.

Please note that if the time zone is set, ical-generator assumes that all times are already in the correct time zone. Alternatively, a moment-timezone or a Luxon object can be passed with setZone, ical-generator will then set the time zone itself.

This and the 'floating' flag (see below) are mutually exclusive, and setting a timezone will unset the 'floating' flag. If neither 'timezone' nor 'floating' are set, the date will be output with in UTC format (see date-time form #2 in section 3.3.5 of RFC 554).

See Readme for details about supported values and timezone handling.

event.timezone('America/New_York');
Copy

Return a shallow copy of the events's options for JSON stringification. Third party objects like moment.js values or RRule objects are stringified as well. Can be used for persistence.

const event = ical().createEvent();
const json = JSON.stringify(event);

// later: restore event data
const calendar = ical().createEvent(JSON.parse(json));
Copy

Return generated event as a string.

const event = ical().createEvent();
console.log(event.toString()); // → BEGIN:VEVENT…
Copy

Get the event's transparency

Set the event's transparency

Set the field to OPAQUE if the person or resource is no longer available due to this event. If the calendar entry has no influence on availability, you can set the field to TRANSPARENT. This value is mostly used to find out if a person has time on a certain date or not (see TRANSP in iCal specification).

import ical, {ICalEventTransparency} from 'ical-generator';
event.transparency(ICalEventTransparency.OPAQUE);
Copy

Get the event's ID

Use this method to set the event's ID. If not set, a UUID will be generated randomly.

Get the event's URL

Set the event's URL

Set X-* attributes. Woun't filter double attributes, which are also added by another method (e.g. summary), so these attributes may be inserted twice.

event.x([
    {
        key: "X-MY-CUSTOM-ATTR",
        value: "1337!"
    }
]);

event.x([
    ["X-MY-CUSTOM-ATTR", "1337!"]
]);

event.x({
    "X-MY-CUSTOM-ATTR": "1337!"
});
Copy

Set a X-* attribute. Woun't filter double attributes, which are also added by another method (e.g. summary), so these attributes may be inserted twice.

event.x("X-MY-CUSTOM-ATTR", "1337!");
Copy

Get all custom X-* attributes.