iCalendar (.ics) import & export

@super-calendar/core ships parseICalendar and toICalendar to convert between .ics text and the library’s CalendarEvent shape — so a calendar built with super-calendar can import feeds from, and export to, Google Calendar, Apple Calendar, Outlook, and anything else that speaks iCal.

import { parseICalendar, toICalendar } from "@super-calendar/core";
// also re-exported from "@super-calendar/dom" and "@super-calendar/native"

Import

parseICalendar(text) returns an array of events you can pass straight to a <Calendar>:

const res = await fetch("/calendar.ics");
const events = parseICalendar(await res.text());

// -> [{ uid, title, start, end, allDay?, description?, location?, recurrence? }]

Each event carries the standard fields it round-trips: uid, description, location, plus allDay (from VALUE=DATE) and a recurrence parsed from RRULE. Recurring events are returned as a single event with a rule — expand them for a date range with expandRecurringEvents:

import { expandRecurringEvents, parseICalendar } from "@super-calendar/core";

const occurrences = expandRecurringEvents(parseICalendar(ics), rangeStart, rangeEnd);

Export

toICalendar(events) produces a complete VCALENDAR string. Timed events are written in UTC; set allDay: true for VALUE=DATE events; a recurrence becomes an RRULE.

const ics = toICalendar(events);

// Offer it as a download in the browser:
const url = URL.createObjectURL(new Blob([ics], { type: "text/calendar" }));

Pass { prodId, now } to set the calendar’s PRODID and the DTSTAMP written on each event. A stable UID is derived from the event when you don’t supply one, so re-exports stay diff-friendly.

What’s covered

A pragmatic subset of RFC 5545, aimed at real-world event interchange:

VEVENT with SUMMARY, DESCRIPTION, LOCATION, UID, DTSTART, and either DTEND or DURATION (e.g. PT1H30M, P1D).
All-day events via VALUE=DATE (a missing end becomes a one-day span).
Dates in UTC (...Z), a named IANA zone (TZID=Europe/London, resolved to the correct instant), floating local, or date-only; line folding and text escaping per the spec.
RRULE round-tripped to a RecurrenceRule (FREQ, INTERVAL, COUNT, UNTIL, weekly BYDAY, and ordinal BYDAY like 3MO/-1FR → nthWeekday), plus EXDATE exception days (recurrence.exdates, honoured by expandRecurringEvents).

Not (yet) handled: VTODO / VJOURNAL, VALARM, attendees, attachments, and embedded VTIMEZONE definitions (a TZID must be a valid IANA name for the runtime’s Intl). Contributions welcome.

Getting started

Views

Events

Styling

Interaction & accessibility

Packages & platforms

Reference

iCalendar (.ics) import & export

Import

Export

What’s covered

​Import

​Export

​What’s covered

Import

Export

What’s covered