ical.js is a comprehensive JavaScript library for parsing and working with iCalendar (RFC 5545), jCal (RFC 7265), vCard (RFC 6350), and jCard (RFC 7095) data formats. It serves as a replacement for libical in web-based calendar applications, enabling developers to parse, manipulate, and generate calendar and contact data directly in JavaScript environments including browsers and Node.js.
npm install ical.jsimport ICAL from "ical.js";For CommonJS:
const ICAL = require("ical.js");Individual imports:
import { parse, stringify, Component, Event, Time } from "ical.js";import ICAL from "ical.js";
// Parse iCalendar data
const icalData = `BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//Example//Example//EN
BEGIN:VEVENT
UID:12345@example.com
DTSTART:20231201T120000Z
DTEND:20231201T130000Z
SUMMARY:Team Meeting
DESCRIPTION:Weekly team standup
END:VEVENT
END:VCALENDAR`;
const jcalData = ICAL.parse(icalData);
const vcalendar = new ICAL.Component(jcalData);
const vevent = vcalendar.getFirstSubcomponent("vevent");
const event = new ICAL.Event(vevent);
console.log(event.summary); // "Team Meeting"
console.log(event.startDate.toString()); // Start date
console.log(event.endDate.toString()); // End date
// Generate iCalendar data
const newEvent = new ICAL.Component("vevent");
newEvent.addPropertyWithValue("uid", "new-event@example.com");
newEvent.addPropertyWithValue("summary", "New Meeting");
newEvent.addPropertyWithValue("dtstart", ICAL.Time.now());
const newCalendar = new ICAL.Component("vcalendar");
newCalendar.addPropertyWithValue("version", "2.0");
newCalendar.addPropertyWithValue("prodid", "-//Example//Example//EN");
newCalendar.addSubcomponent(newEvent);
const icalString = ICAL.stringify(newCalendar.jCal);
console.log(icalString);ical.js is built around several key architectural components:
parse()stringify()ComponentPropertyEventTimeVCardTimeDurationPeriodRecurRecurExpansionRecurIteratorTimezoneTimezoneServiceUtcOffsetHigh-level parsing and serialization functions for converting between iCalendar/vCard strings and structured jCal/jCard objects.
function parse(input: string): object | object[];
function stringify(jCal: array): string;Comprehensive time representation classes for handling dates, times, durations, and periods with full timezone support and RFC compliance.
class Time {
constructor(data?: object, zone?: Timezone);
static fromString(aValue: string, aProperty?: Property): Time;
static fromJSDate(aDate: Date, useUTC?: boolean): Time;
static now(): Time;
}
class Duration {
constructor(data?: object);
static fromString(aStr: string): Duration;
static fromSeconds(aSeconds: number): Duration;
}Object-oriented wrappers for working with calendar components and properties, providing convenient methods for manipulation and access.
class Component {
constructor(jCal: array, parent?: Component);
static fromString(str: string): Component;
getFirstSubcomponent(name: string): Component | null;
getFirstProperty(name: string): Property | null;
addSubcomponent(component: Component): void;
addPropertyWithValue(name: string, value: any): Property;
}
class Event {
constructor(component: Component, options?: object);
get summary(): string;
get startDate(): Time;
get endDate(): Time;
iterator(startTime?: Time): RecurExpansion;
}Complete implementation of RFC 5545 recurrence rules with expansion engines for generating recurring event instances.
class Recur {
constructor(data?: object);
static fromString(string: string): Recur;
iterator(aStart: Time): RecurIterator;
getNextOccurrence(aStartTime: Time, aRecurrenceId?: Time): Time;
}
class RecurExpansion {
constructor(options: object);
next(): Time | null;
}Comprehensive timezone handling with support for VTIMEZONE components, UTC offset calculations, and timezone conversions.
class Timezone {
constructor(data?: object);
static fromData(aData: object): Timezone;
static get utcTimezone(): Timezone;
static get localTimezone(): Timezone;
utcOffset(tt: Time): number;
}
const TimezoneService: {
get(tzid: string): Timezone | null;
register(timezone: Timezone, name?: string): void;
reset(): void;
};Various utility classes and helper functions for specialized data handling, binary data processing, and internal operations.
class Binary {
constructor(aValue?: string);
static fromString(aString: string): Binary;
decodeValue(): string;
toString(): string;
}
const helpers: {
updateTimezones(vcal: Component): void;
clone(aSrc: any, aDeep?: boolean): any;
foldline(aLine: string): string;
};
const design: {
strict: boolean;
defaultSet: object;
icalendar: object;
vcard: object;
vcard3: object;
};ical.js provides several global configuration options:
ICAL.foldLength = 75; // Characters before line folding
ICAL.debug = false; // Debug mode flag
ICAL.newLineChar = '\r\n'; // Line ending charactersThe library may throw various errors during parsing and processing:
Always wrap parsing operations in try-catch blocks when working with untrusted input data.