Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 555 Commits
.github/workflows		.github/workflows
src		src
test		test
.babelrc		.babelrc
.gitignore		.gitignore
.nvmrc		.nvmrc
.travis.yml		.travis.yml
Gemfile		Gemfile
LICENSE		LICENSE
README.md		README.md
gulpfile.js		gulpfile.js
index.d.ts		index.d.ts
notes.md		notes.md
package-lock.json		package-lock.json
package.json		package.json

Repository files navigation

ics

TheiCalendar generator

Install

npm install -S ics

Example Usage

In node / CommonJS

Create an iCalendar event:

constics=require('ics')// or, in ESM: import * as ics from 'ics'constevent={start:[2018,5,30,6,30],duration:{hours:6,minutes:30},title:'Bolder Boulder',description:'Annual 10-kilometer run in Boulder, Colorado',location:'Folsom Field, University of Colorado (finish line)',url:'http://www.bolderboulder.com/',geo:{lat:40.0095,lon:105.2669},categories:['10k races','Memorial Day Weekend','Boulder CO'],status:'CONFIRMED',busyStatus:'BUSY',organizer:{name:'Admin',email:'Race@BolderBOULDER.com'},attendees:[{name:'Adam Gibbons',email:'adam@example.com',rsvp:true,partstat:'ACCEPTED',role:'REQ-PARTICIPANT'},{name:'Brittany Seaton',email:'brittany@example2.org',dir:'https://linkedin.com/in/brittanyseaton',role:'OPT-PARTICIPANT'}]}ics.createEvent(event,(error,value)=>{if(error){console.log(error)return}console.log(value)})// BEGIN:VCALENDAR// VERSION:2.0// CALSCALE:GREGORIAN// PRODID:adamgibbons/ics// METHOD:PUBLISH// X-PUBLISHED-TTL:PT1H// BEGIN:VEVENT// UID:S8h0Vj7mTB74p9vt5pQzJ// SUMMARY:Bolder Boulder// DTSTAMP:20181017T204900Z// DTSTART:20180530T043000Z// DESCRIPTION:Annual 10-kilometer run in Boulder\, Colorado// X-MICROSOFT-CDO-BUSYSTATUS:BUSY// URL:http://www.bolderboulder.com/// GEO:40.0095;105.2669// LOCATION:Folsom Field, University of Colorado (finish line)// STATUS:CONFIRMED// CATEGORIES:10k races,Memorial Day Weekend,Boulder CO// ORGANIZER;CN=Admin:mailto:Race@BolderBOULDER.com// ATTENDEE;RSVP=TRUE;ROLE=REQ-PARTICIPANT;PARTSTAT=ACCEPTED;CN=Adam Gibbons:mailto:adam@example.com// ATTENDEE;RSVP=FALSE;ROLE=OPT-PARTICIPANT;DIR=https://linkedin.com/in/brittanyseaton;CN=Brittany//   Seaton:mailto:brittany@example2.org// DURATION:PT6H30M// END:VEVENT// END:VCALENDAR

Write an iCalendar file:

const{ writeFileSync}=require('fs')constics=require('ics')ics.createEvent({title:'Dinner',description:'Nightly thing I do',busyStatus:'FREE',start:[2018,1,15,6,30],duration:{minutes:50}},(error,value)=>{if(error){console.log(error)}writeFileSync(`${__dirname}/event.ics`,value)/*You 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]const blob = new Blob([value], { type: 'text/calendar' });        saveAs(blob, `${title}.ics`);*/})

Create multiple iCalendar events:

constics=require('./dist')const{ error, value}=ics.createEvents([{title:'Lunch',start:[2018,1,15,12,15],duration:{minutes:45}},{title:'Dinner',start:[2018,1,15,12,15],duration:{hours:1,minutes:30}}])if(error){console.log(error)return}console.log(value)// BEGIN:VCALENDAR// VERSION:2.0// CALSCALE:GREGORIAN// PRODID:adamgibbons/ics// METHOD:PUBLISH// X-PUBLISHED-TTL:PT1H// BEGIN:VEVENT// UID:pP83XzQPo5RlvjDCMIINs// SUMMARY:Lunch// DTSTAMP:20230917T142209Z// DTSTART:20180115T121500Z// DURATION:PT45M// END:VEVENT// BEGIN:VEVENT// UID:gy5vfUVv6wjyBeNkkFmBX// SUMMARY:Dinner// DTSTAMP:20230917T142209Z// DTSTART:20180115T121500Z// DURATION:PT1H30M// END:VEVENT// END:VCALENDAR

Create iCalendar events with Audio (Mac):

letics=require("ics")letmoment=require("moment")letevents=[]letalarms=[]letstart=moment().format('YYYY-M-D-H-m').split("-").map((a)=>parseInt(a))letend=moment().add({'hours':2,"minutes":30}).format("YYYY-M-D-H-m").split("-").map((a)=>parseInt(a))alarms.push({action:'audio',description:'Reminder',trigger:{hours:2,minutes:30,before:true},repeat:2,attachType:'VALUE=URI',attach:'Glass'})letevent={productId:"myCalendarId",uid:"123"+"@ics.com",startOutputType:"local",start:start,end:end,title:"test here",alarms:alarms}events.push(event)console.log(ics.createEvents(events).value)// BEGIN:VCALENDAR// VERSION:2.0// CALSCALE:GREGORIAN// PRODID:myCalendarId// METHOD:PUBLISH// X-PUBLISHED-TTL:PT1H// BEGIN:VEVENT// UID:123@ics.com// SUMMARY:test here// DTSTAMP:20230917T142621Z// DTSTART:20230917T152600// DTEND:20230917T175600// BEGIN:VALARM// ACTION:AUDIO// REPEAT:2// DESCRIPTION:Reminder// ATTACH;VALUE=URI:Glass// TRIGGER:-PT2H30M\nEND:VALARM// END:VEVENT// END:VCALENDAR

Using ESModules & in the browser

import{createEvent}from'ics';constevent={  ...}asyncfunctionhandleDownload(){constfilename='ExampleEvent.ics'constfile=awaitnewPromise((resolve,reject)=>{createEvent(event,(error,value)=>{if(error){reject(error)}resolve(newFile([value],filename,{type:'text/calendar'}))})})consturl=URL.createObjectURL(file);// trying to assign the file URL to a window could cause cross-site// issues so this is a workaround using HTML5constanchor=document.createElement('a');anchor.href=url;anchor.download=filename;document.body.appendChild(anchor);anchor.click();document.body.removeChild(anchor);URL.revokeObjectURL(url);}

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 },wherevalue 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 thestart 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 aDate).

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 inRFC 5545)
end	Time at which event ends.Either`end` or`duration` is required, butnot 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 inRFC 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, butnot 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 beglobally unique. It is recommended that it follow theRFC 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 thisone.	`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. SeeMicrosoft 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. SeeiCalender 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 thecalendar (not event) name. Used by Apple iCal and Microsoft Outlook; seeOpen 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 anall-day event, pass only three values (year,month, anddate) to thestart andend properties.The date of theend property should be the dayafter your all-day event.For example, in order to create an all-day event occuring on October 15, 2018:

consteventAttributes={start:[2018,10,15],end:[2018,10,16],/* rest of attributes */}

`callback`

Optional.Node-style callback.

function(err,value){if(err){// if iCal generation fails, err is an object containing the reason// if iCal generation succeeds, err is null}console.log(value)// iCal-compliant text string}

`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 stringiferror isnull.

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

`events`

Array ofattributes objects (as described increateEvent).

`callback`

Optional.Node-style callback.

function(err,value){if(err){// if iCal generation fails, err is an object containing the reason// if iCal generation succeeds, err is null}console.log(value)// iCal-compliant text string}