iCal Time zone information for JavaScript

This tool converts the most recent IANA (formerly Olson) time zone database files into VTIMEZONE blocks, which are compatible with the iCalendar specification (RFC2445).
It is optimized to be easily used in every JavaScript project; may it be VanillaJS, React, Angular, Vue, Svelte, or based on any other framework or library.

Give it a try!

    • No results found.
    Please select a time zone above...
    Please select a time zone above...

    Get the Code!

    📦 How to install

    Simply install the package via npm:

    npm install timezones-ical-library

    ... and import it for commonJS approaches with:

    const tzLib = require('timezones-ical-library');

    ... or (preferred) with ES support:

    import { tzlib_get_ical_block, tzlib_get_offset, tzlib_get_timezones } from 'timezones-ical-library';

    ⚙️ How to use

    Get time zones

    Use `tzlib_get_timezones()` to retrieve a list of all available time zone strings. You can pass `true` to retrieve a JSON formatted string instead of an array.

    Get the iCal time zone block

    Use the `tzlib_get_ical_block(tzName)` function to return the proper iCal VTIMEZONE block for a given time zone string (tzName). Again, pass `true` to retrieve a JSON formatted string instead of an array (not recommended).
    You will receive an array, holding the VTIMEZONE block first, and the TZID line (additionally) second. The latter one is needed for any further time statement.
    Include this into your further iCal data to come up with a complete ics file.
    A final constellation could look like this:

    BEGIN:VCALENDAR
    VERSION:2.0
    PRODID:-// github.com/add2cal/add-to-calendar-button //EN
    CALSCALE:GREGORIAN
    
    BEGIN:VTIMEZONE
    TZID:America/New_York
    LAST-MODIFIED:20220824T133813Z
    X-LIC-LOCATION:America/New_York
    BEGIN:DAYLIGHT
    TZNAME:EDT
    TZOFFSETFROM:-0500
    TZOFFSETTO:-0400
    DTSTART:19700308T020000
    RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
    END:DAYLIGHT
    BEGIN:STANDARD
    TZNAME:EST
    TZOFFSETFROM:-0400
    TZOFFSETTO:-0500
    DTSTART:19701101T020000
    RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
    END:STANDARD
    END:VTIMEZONE
    
    BEGIN:VEVENT
    UID:2022-08-30T19:29:38.618Z@add-to-calendar-button
    DTSTAMP:20230214T091500Z
    DTSTART;TZID=America/New_York:20230214T091500
    DTEND;TZID=America/New_York:20230218T223000
    SUMMARY:A sample event
    DESCRIPTION:Just some descriptive text...
    LOCATION:World Wide Web
    STATUS:CONFIRMED
    LAST-MODIFIED:20220830T192938Z
    SEQUENCE:0
    END:VEVENT
    END:VCALENDAR

    Get a specific offset

    Use `tzlib_get_offset(tzName, isoDate, isoTime)` to get specific offset (relative to UTC), based on a provided date and time.
    For example, you can provide tzName 'Europe/Berlin', isoDate '2023-05-23', and isoTime '15:45' in order to retrieve the offset, which applies for this time zone at the 23rd of May in 2023 at exactly 15:45.


    ⚙️ Use it via API

    Alternatively to the installation, you can make use of the public API.

    Get time zones via API

    Get them directly via https://tz.add-to-calendar-technology.com/api/zones.json.

    Get the iCal time zone block via API

    Once you have a valid zone name ready, you can get the ics part directly via the following URL scheme:

    https://tz.add-to-calendar-technology.com/api/%zoneName%.ics

    With %zoneName% being your time zone.
    So, for New York, this would be https://tz.add-to-calendar-technology.com/api/America/New_York.ics.
    This is case sensitive!

    (Mind that this does not deliver a fully valid ics file, since it only contains the VTIMEZONE part. You will need to combine this with your other event information.)


    Background story

    Time zones are a tricky thing. Especially because they do not follow any logical rules, but are rather randomly made up by politicians (and other people). This makes life hard for any software developer dealing with time.

    Working on the Add to Calendar Button project, I was facing the same issue.
    Generating iCal/ics files strictly requires time zone information - at least if you start dealing with recurring events. This time zone information needs to be more or less manually inserted. I started searching for some kind of official database or API.
    There were a lot of libraries, which are quite big in terms of functionality and also size. Most of this is dangerous overhead, when you only need time zone information. No API, of course. Basically, nothing of any use to me.
    The official database, on the other hand, is not directly accessible - especially not via JavaScript.

    That's why I came up with this open source repository, pulling the latest official data, making it usable via JavaScript, and offering the most essential data, while stripping out all the rest - for best performance and bundle size.


    v1.8.0