Constructor of [[ICalEvent]. The calendar reference is
required to query the calendar's timezone when required.
Calendar Event Data
Reference to ICalCalendar object
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]
Set the event's allDay flag.
event.allDay(true); // → appointment is for the whole day
import ical from 'ical-generator';
const cal = ical();
cal.createEvent({
start: new Date('2020-01-01'),
summary: 'Very Important Day',
allDay: true
});
cal.toString();
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
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]
3.2.0-develop.1
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]
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);
Add categories to the event or return all selected categories.
const event = ical().createEvent();
cal.categories([
{name: 'APPOINTMENT'},
{name: 'MEETING'}
]);
cal.categories(); // --> [ICalCategory, ICalCategory]
Set the event's class
import ical, { ICalEventClass } from 'ical-generator';
event.class(ICalEventClass.PRIVATE);
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
});
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');
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>');
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
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');
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'
});
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>'
});
DESCRIPTION:Hello World!
X-ALT-DESC;FMTTYPE=text/html:<p>Hello World!</p>
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.
Use this method to set the event's ID. If not set, a UUID will be generated randomly.
Event ID you want to set
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
}
});
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
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
}
});
GEO:52.50363;13.32865
Set the event's organizer
event.organizer({
name: 'Organizer\'s Name',
email: 'organizer@example.com'
});
// OR
event.organizer('Organizer\'s Name <organizer@example.com>');
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'
})
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
});
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();
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
Set the event's repeating options by passing an RRule object.
2.0.0-develop.5
import ical from 'ical-generator';
import { datetime, RRule } from 'rrule';
const cal = ical();
const event = cal.createEvent({
start: new Date('2020-01-01T20:00:00Z'),
summary: 'Repeating Event'
});
const rule = new RRule({
freq: RRule.WEEKLY,
interval: 5,
byweekday: [RRule.MO, RRule.FR],
dtstart: datetime(2012, 2, 1, 10, 30),
until: datetime(2012, 12, 31)
})
event.repeating(rule);
cal.toString();
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//sebbo.net//ical-generator//EN
BEGIN:VEVENT
UID:36585e40-8fa8-460d-af0c-88b6f434030b
SEQUENCE:0
DTSTAMP:20240212T193827Z
DTSTART:20200101T200000Z
RRULE:FREQ=WEEKLY;INTERVAL=5;BYDAY=MO,FR;UNTIL=20121231T000000Z
SUMMARY:Repeating Event
END:VEVENT
END:VCALENDAR
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.
Sequence number or null to unset it
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();
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
Set the event's status
import ical, {ICalEventStatus} from 'ical-generator';
event.status(ICalEventStatus.CONFIRMED);
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.
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');
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));
Return generated event as a string.
const event = ical().createEvent();
console.log(event.toString()); // → BEGIN:VEVENT…
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);
Use this method to set the event's ID. If not set, a UUID will be generated randomly.
Event ID you want to set
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!"
});
Usually you get an ICalEvent object like this: