ics

The iCalendar generator

Install

npm install -S ics

Example Usage

In node / CommonJS

1. Create an iCalendar event:

1const ics = require('ics')
2// or, in ESM: import * as ics from 'ics'
3
4const event = {
5  start: [2018, 5, 30, 6, 30],
6  duration: { hours: 6, minutes: 30 },
7  title: 'Bolder Boulder',
8  description: 'Annual 10-kilometer run in Boulder, Colorado',
9  location: 'Folsom Field, University of Colorado (finish line)',
10  url: 'http://www.bolderboulder.com/',
11  geo: { lat: 40.0095, lon: 105.2669 },
12  categories: ['10k races', 'Memorial Day Weekend', 'Boulder CO'],
13  status: 'CONFIRMED',
14  busyStatus: 'BUSY',
15  organizer: { name: 'Admin', email: 'Race@BolderBOULDER.com' },
16  attendees: [
17    { name: 'Adam Gibbons', email: 'adam@example.com', rsvp: true, partstat: 'ACCEPTED', role: 'REQ-PARTICIPANT' },
18    { name: 'Brittany Seaton', email: 'brittany@example2.org', dir: 'https://linkedin.com/in/brittanyseaton', role: 'OPT-PARTICIPANT' }
19  ]
20}
21
22ics.createEvent(event, (error, value) => {
23  if (error) {
24    console.log(error)
25    return
26  }
27
28  console.log(value)
29})
30// BEGIN:VCALENDAR
31// VERSION:2.0
32// CALSCALE:GREGORIAN
33// PRODID:adamgibbons/ics
34// METHOD:PUBLISH
35// X-PUBLISHED-TTL:PT1H
36// BEGIN:VEVENT
37// UID:S8h0Vj7mTB74p9vt5pQzJ
38// SUMMARY:Bolder Boulder
39// DTSTAMP:20181017T204900Z
40// DTSTART:20180530T043000Z
41// DESCRIPTION:Annual 10-kilometer run in Boulder\, Colorado
42// X-MICROSOFT-CDO-BUSYSTATUS:BUSY
43// URL:http://www.bolderboulder.com/
44// GEO:40.0095;105.2669
45// LOCATION:Folsom Field, University of Colorado (finish line)
46// STATUS:CONFIRMED
47// CATEGORIES:10k races,Memorial Day Weekend,Boulder CO
48// ORGANIZER;CN=Admin:mailto:Race@BolderBOULDER.com
49// ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Adam Gibbons:mailto:adam@example.com
50// ATTENDEE;RSVP=FALSE;ROLE=OPT-PARTICIPANT;DIR=https://linkedin.com/in/brittanyseaton;CN=Brittany
51//   Seaton:mailto:brittany@example2.org
52// DURATION:PT6H30M
53// END:VEVENT
54// END:VCALENDAR

2. Write an iCalendar file:

1const { writeFileSync } = require('fs')
2const ics = require('ics')
3
4ics.createEvent({
5  title: 'Dinner',
6  description: 'Nightly thing I do',
7  busyStatus: 'FREE',
8  start: [2018, 1, 15, 6, 30],
9  duration: { minutes: 50 }
10}, (error, value) => {
11  if (error) {
12    console.log(error)
13  }
14
15  writeFileSync(`${__dirname}/event.ics`, value)
16
17/*
18You cannot use fs in Frontend libraries like React so you rather import a module to save files to the browser as follow [  import { saveAs } from 'file-saver'; // For saving the file in the browser]
19const blob = new Blob([value], { type: 'text/calendar' });
20        saveAs(blob, `${title}.ics`);
21
22*/
23})

3. Create multiple iCalendar events:

1const ics = require('./dist')
2
3const { error, value } = ics.createEvents([
4  {
5    title: 'Lunch',
6    start: [2018, 1, 15, 12, 15],
7    duration: { minutes: 45 }
8  },
9  {
10    title: 'Dinner',
11    start: [2018, 1, 15, 12, 15],
12    duration: { hours: 1, minutes: 30 }
13  }
14])
15
16if (error) {
17  console.log(error)
18  return
19}
20
21console.log(value)
22// BEGIN:VCALENDAR
23// VERSION:2.0
24// CALSCALE:GREGORIAN
25// PRODID:adamgibbons/ics
26// METHOD:PUBLISH
27// X-PUBLISHED-TTL:PT1H
28// BEGIN:VEVENT
29// UID:pP83XzQPo5RlvjDCMIINs
30// SUMMARY:Lunch
31// DTSTAMP:20230917T142209Z
32// DTSTART:20180115T121500Z
33// DURATION:PT45M
34// END:VEVENT
35// BEGIN:VEVENT
36// UID:gy5vfUVv6wjyBeNkkFmBX
37// SUMMARY:Dinner
38// DTSTAMP:20230917T142209Z
39// DTSTART:20180115T121500Z
40// DURATION:PT1H30M
41// END:VEVENT
42// END:VCALENDAR

4. Create iCalendar events with Audio (Mac):

1let ics = require("ics")
2let moment = require("moment")
3let events = []
4let alarms = []
5
6let start = moment().format('YYYY-M-D-H-m').split("-").map((a) => parseInt(a))
7let end = moment().add({'hours':2, "minutes":30}).format("YYYY-M-D-H-m").split("-").map((a) => parseInt(a))
8
9alarms.push({
10  action: 'audio',
11  description: 'Reminder',
12  trigger: {hours:2,minutes:30,before:true},
13  repeat: 2,
14  attachType:'VALUE=URI',
15  attach: 'Glass'
16})
17
18let event = {
19  productId:"myCalendarId",
20  uid: "123"+"@ics.com",
21  startOutputType:"local",
22  start: start,
23  end: end,
24  title: "test here",
25  alarms: alarms
26}
27events.push(event)
28console.log(ics.createEvents(events).value)
29
30// BEGIN:VCALENDAR
31// VERSION:2.0
32// CALSCALE:GREGORIAN
33// PRODID:myCalendarId
34// METHOD:PUBLISH
35// X-PUBLISHED-TTL:PT1H
36// BEGIN:VEVENT
37// UID:123@ics.com
38// SUMMARY:test here
39// DTSTAMP:20230917T142621Z
40// DTSTART:20230917T152600
41// DTEND:20230917T175600
42// BEGIN:VALARM
43// ACTION:AUDIO
44// REPEAT:2
45// DESCRIPTION:Reminder
46// ATTACH;VALUE=URI:Glass
47// TRIGGER:-PT2H30M\nEND:VALARM
48// END:VEVENT
49// END:VCALENDAR

Using ESModules & in the browser

1import { createEvent} from 'ics';
2
3const event = {
4  ...
5}
6
7async function handleDownload() {
8  const filename = 'ExampleEvent.ics'
9  const file = await new Promise((resolve, reject) => {
10    createEvent(event, (error, value) => {
11      if (error) {
12        reject(error)
13      }
14
15      resolve(new File([value], filename, { type: 'text/calendar' }))
16    })
17  })
18  const url = URL.createObjectURL(file);
19
20  // trying to assign the file URL to a window could cause cross-site
21  // issues so this is a workaround using HTML5
22  const anchor = document.createElement('a');
23  anchor.href = url;
24  anchor.download = filename;
25
26  document.body.appendChild(anchor);
27  anchor.click();
28  document.body.removeChild(anchor);
29
30  URL.revokeObjectURL(url);
31}

API

createEvent(attributes[, callback])

Generates an iCal-compliant VCALENDAR string with one VEVENT. If a callback is not provided, returns an object having the form { error, value }, where value contains an iCal-compliant string if there are no errors. If a callback is provided, returns a Node-style callback.

attributes

Object literal containing event information. Only the start property is required.

Note all date/time fields can be the array form, or a number representing the unix timestamp in milliseconds (e.g. getTime() on a Date).

The following properties are accepted:

Property	Description	Example
start	Required. Date and time at which the event begins.	[2000, 1, 5, 10, 0] (January 5, 2000) or a number
startInputType	Type of the date/time data in start: local (default): passed data is in local time. utc: passed data is UTC
startOutputType	Format of the start date/time in the output: utc (default): the start date will be sent in UTC format. local: the start date will be sent as "floating" (form #1 in RFC 5545)
end	Time at which event ends. Either end or duration is required, but not both.	[2000, 1, 5, 13, 5] (January 5, 2000 at 1pm) or a number
endInputType	Type of the date/time data in end: local: passed data is in local time. utc: passed data is UTC. The default is the value of startInputType
endOutputType	Format of the start date/time in the output: utc: the start date will be sent in UTC format. local: the start date will be sent as "floating" (form #1 in RFC 5545). The default is the value of startOutputType
duration	How long the event lasts. Object literal having form { weeks, days, hours, minutes, seconds } Either end or duration is required, but not both.	{ hours: 1, minutes: 45 } (1 hour and 45 minutes)
title	Title of event.	'Code review'
description	Description of event.	'A constructive roasting of those seeking to merge into master branch'
location	Intended venue	Mountain Sun Pub and Brewery
geo	Geographic coordinates (lat/lon)	{ lat: 38.9072, lon: 77.0369 }
url	URL associated with event	'http://www.mountainsunpub.com/'
status	Three statuses are allowed: TENTATIVE, CONFIRMED, CANCELLED	CONFIRMED
organizer	Person organizing the event	{ name: 'Adam Gibbons', email: 'adam@example.com', dir: 'https://linkedin.com/in/adamgibbons', sentBy: 'test@example.com' }
attendees	Persons invited to the event	[{ name: 'Mo', email: 'mo@foo.com', rsvp: true }, { name: 'Bo', email: 'bo@bar.biz', dir: 'https://twitter.com/bo1234', partstat: 'ACCEPTED', role: 'REQ-PARTICIPANT' }]
categories	Categories associated with the event	['hacknight', 'stout month']
alarms	Alerts that can be set to trigger before, during, or after the event. The following attach properties work on Mac OS: Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sousumi, Submarine, Tink	{ action: 'display', description: 'Reminder', trigger: [2000, 1, 4, 18, 30] } OR { action: 'display', description: 'Reminder', trigger: { hours: 2, minutes: 30, before: true } } OR { action: 'display', description: 'Reminder', trigger: { hours: 2, minutes: 30, before: false } OR { action: 'audio', description: 'Reminder', trigger: { hours: 2, minutes: 30, before: true }, repeat: 2, attachType: 'VALUE=URI', attach: 'Glass' }
productId	Product which created ics, PRODID field	'adamgibbons/ics'
uid	Universal unique id for event, produced by default with nanoid. Warning: This value must be globally unique. It is recommended that it follow the RFC 822 addr-spec (i.e. localpart@domain). Including the @domain half is a good way to ensure uniqueness.	'LZfXLFzPPR4NNrgjlWDxn'
method	This property defines the iCalendar object method associated with the calendar object. When used in a MIME message entity, the value of this property MUST be the same as the Content-Type "method" parameter value. If either the "METHOD" property or the Content-Type "method" parameter is specified, then the other MUST also be specified.	PUBLISH
recurrenceRule	A recurrence rule, commonly referred to as an RRULE, defines the repeat pattern or rule for to-dos, journal entries and events. If specified, RRULE can be used to compute the recurrence set (the complete set of recurrence instances in a calendar component). You can use a generator like this one.	FREQ=DAILY
exclusionDates	Array of date-time exceptions for recurring events, to-dos, journal entries, or time zone definitions.	[[2000, 1, 5, 10, 0], [2000, 2, 5, 10, 0]] OR [1694941727477, 1694945327477]
sequence	For sending an update for an event (with the same uid), defines the revision sequence number.	2
busyStatus	Used to specify busy status for Microsoft applications, like Outlook. See Microsoft spec.	'BUSY' OR 'FREE' OR 'TENTATIVE' OR 'OOF'
transp	Used to specify event transparency (does event consume actual time of an individual). Used by Google Calendar to determine if event should change attendees availability to 'Busy' or not.	'TRANSPARENT' OR 'OPAQUE'
classification	This property defines the access classification for a calendar component. See iCalender spec.	'PUBLIC' OR 'PRIVATE' OR 'CONFIDENTIAL' OR any non-standard string
created	Date-time representing event's creation date. Provide a date-time in local time	[2000, 1, 5, 10, 0] or a number
lastModified	Date-time representing date when event was last modified. Provide a date-time in local time	[2000, 1, 5, 10, 0] or a number
calName	Specifies the calendar (not event) name. Used by Apple iCal and Microsoft Outlook; see Open Specification	'Example Calendar'
htmlContent	Used to include HTML markup in an event's description. Standard DESCRIPTION tag should contain non-HTML version.	<!DOCTYPE html><html><body><p>This is<br>test<br>html code.</p></body></html>

To create an all-day event, pass only three values (year, month, and date) to the start and end properties. The date of the end property should be the day after your all-day event. For example, in order to create an all-day event occuring on October 15, 2018:

1const eventAttributes = {
2  start: [2018, 10, 15],
3  end: [2018, 10, 16],
4  /* rest of attributes */
5}

callback

Optional. Node-style callback.

1function (err, value) {
2  if (err) {
3    // if iCal generation fails, err is an object containing the reason
4    // if iCal generation succeeds, err is null
5  }
6
7  console.log(value) // iCal-compliant text string
8}

createEvents(events[, headerParams, callback])

Generates an iCal-compliant VCALENDAR string with multiple VEVENTS.

headerParams may be omitted, and in this case they will be read from the first event.

If a callback is not provided, returns an object having the form { error, value }, where value is an iCal-compliant text string if error is null.

If a callback is provided, returns a Node-style callback.

events

Array of attributes objects (as described in createEvent).

callback

Optional. Node-style callback.

1function (err, value) {
2  if (err) {
3    // if iCal generation fails, err is an object containing the reason
4    // if iCal generation succeeds, err is null
5  }
6
7  console.log(value) // iCal-compliant text string
8}

Develop

Run mocha tests and watch for changes:

npm start

Run tests once and exit:

npm test

Build the project, compiling all ES6 files within the src directory into vanilla JavaScript in the dist directory.

npm run build

References

• RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar)
• iCalendar Validator