ical.js

What is ical.js?

ical.js is a JavaScript library for parsing and manipulating iCalendar data. It allows you to create, parse, and manipulate iCalendar files, which are commonly used for calendar events and scheduling.

What are ical.js's main functionalities?

Parsing iCalendar Data

This feature allows you to parse iCalendar data from a string and extract information from it. In this example, we parse an iCalendar string and extract the summary of the first event.

const ICAL = require('ical.js');
const icalData = 'BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nSUMMARY:Test Event\nDTSTART:20230301T120000Z\nDTEND:20230301T130000Z\nEND:VEVENT\nEND:VCALENDAR';
const jcalData = ICAL.parse(icalData);
const comp = new ICAL.Component(jcalData);
const vevent = comp.getFirstSubcomponent('vevent');
const summary = vevent.getFirstPropertyValue('summary');
console.log(summary); // Output: Test Event

Creating iCalendar Data

This feature allows you to create iCalendar data programmatically. In this example, we create a new event with a summary, start time, and end time, and then convert it to an iCalendar string.

const ICAL = require('ical.js');
const event = new ICAL.Component(['vcalendar', [], [
  ['vevent', [], [
    ['summary', {}, 'text', 'New Event'],
    ['dtstart', {}, 'date-time', '20230301T120000Z'],
    ['dtend', {}, 'date-time', '20230301T130000Z']
  ]]
]]);
const icalString = event.toString();
console.log(icalString);

Manipulating iCalendar Data

This feature allows you to manipulate existing iCalendar data. In this example, we parse an iCalendar string, update the summary of the first event, and then convert it back to an iCalendar string.

const ICAL = require('ical.js');
const icalData = 'BEGIN:VCALENDAR\nVERSION:2.0\nBEGIN:VEVENT\nSUMMARY:Test Event\nDTSTART:20230301T120000Z\nDTEND:20230301T130000Z\nEND:VEVENT\nEND:VCALENDAR';
const jcalData = ICAL.parse(icalData);
const comp = new ICAL.Component(jcalData);
const vevent = comp.getFirstSubcomponent('vevent');
vevent.updatePropertyWithValue('summary', 'Updated Event');
const updatedIcalString = comp.toString();
console.log(updatedIcalString);

Other packages similar to ical.js

ical

The 'ical' package is a lightweight iCalendar parser for Node.js. It focuses on parsing iCalendar data and extracting information from it. Compared to ical.js, it is simpler and more focused on parsing rather than creating or manipulating iCalendar data.

node-ical

The 'node-ical' package is a comprehensive iCalendar library for Node.js. It supports parsing, creating, and manipulating iCalendar data. It is similar to ical.js in terms of functionality but is designed specifically for Node.js environments.

ical-generator

The 'ical-generator' package is a library for generating iCalendar files in Node.js. It focuses on creating iCalendar data programmatically. Compared to ical.js, it is more specialized in generating iCalendar data rather than parsing or manipulating existing data.

README

ical.js - Javascript parser for iCalendar, jCal, vCard, jCard.

This is a library to parse the formats defined in the following rfcs and their extensions:

• rfc 5545 (iCalendar)
• rfc7265 (jCal)
• rfc6350 (vCard)
• rfc7095 (jCard)

The initial goal was to use it as a replacement for libical in the Mozilla Calendar Project, but the library has been written with the web in mind. This library enables you to do all sorts of cool experiments with calendar data and the web. Most algorithms here were taken from libical. If you are bugfixing this library, please check if the fix can be upstreamed to libical.

Sandbox and Validator

If you want to try out ICAL.js right now, there is a jsfiddle set up and ready to use.

The ICAL validator demonstrates how to use the library in a webpage, and helps verify iCalendar and jCal. Try the validator online

The recurrence tester calculates occurrences based on a RRULE. It can be used to aid in creating test cases for the recurrence iterator. Try the recurrence tester online.

Installing

ICAL.js has no dependencies and is written in modern JavaScript. You can install ICAL.js via npm, if you would like to use it in Node.js:

npm install ical.js

Then simply import it for use:

import ICAL from "ical.js";

If you are working with a browser, be aware this is an ES6 module:

<script type="module">
  import ICAL from "https://unpkg.com/ical.js/dist/ical.min.js";
  document.querySelector("button").addEventListener("click", () => {
    ICAL.parse(document.getElementById("txt").value);
  });
</script>

If you need to make use of a script tag, you can use the transpiled ES5 version:

<script src="https://unpkg.com/ical.js/dist/ical.es5.min.cjs"></script>
<textarea id="txt"></textarea>
<button onclick="ICAL.parse(document.getElementById('txt').value)"></button>

The browser examples above use the minified versions of the library, which is probably what you want. However, there are also unminified versions of ICAL.js available on unpkg.

• Unminified ES6 module: https://unpkg.com/ical.js/dist/ical.js
• Unminified ES5 version: https://unpkg.com/ical.js/dist/ical.es5.cjs

Timezones

The stock ical.js does not register any timezones, due to the additional size it brings. If you'd like to do timezone conversion, and the timezone definitions are not included in the respective ics files, you'll need to use ical.timezones.js or its minified counterpart.

This file is not included in the distribution since it pulls in IANA timezones that might change regularly. See the github actions on building your own timezones during CI, or grab a recent build from main.

Documentation

For a few guides with code samples, please check out the wiki. If you prefer, full API documentation is available here. If you are missing anything, please don't hesitate to create an issue.

Developing

To contribute to ICAL.js you need to set up the development environment. A simple npm install will get you set up. If you would like to help out and would like to discuss any API changes, please feel free to create an issue.

Tests

The following test suites are available

npm run test-unit         # Node unit tests
npm run test-acceptance   # Node acceptance tests
npm run test-performance  # Performance comparison tests
npm run test-browser      # Browser unit and acceptance tests

npm run test              # Node unit and acceptance tests (This is fast and covers most aspects)
npm run test-all          # All of the above

See the wiki for more details.

Code coverage is automatically generated for the node unit tests. You can view the coverage results online, or run them locally to make sure new code is covered.

Linters

To make sure all ICAL.js code uses a common style, please run the linters using npm run lint. Please make sure you fix any issues shown by this command before sending a pull request.

Documentation

You can generate the documentation locally, this is also helpful to ensure the jsdoc you have written is valid. To do so, run npm run jsdoc. You will find the output in the docs/api/ subdirectory.

Packaging

When you are done with your work, you can run npm run build to create the single-file build for use in the browser, including its minified counterpart and the source map.

License

ical.js is licensed under the Mozilla Public License, version 2.0.