Add-to-calendar links

TLDR

Add-to calendar links are a HTML-only way to let people add your event to their own calendar.

Support varies between calendar apps:

Google calendar

Google took down the documentation for ATC links, but they do work.

The base URL is calendar.google.com/calendar/render?action=TEMPLATE followed by one or more query parameters for your event data:

text (required) – Event title
dates (required) – Start and end dates/times in UTC format (YYYYMMDDThhmmssZ), separated by /.
- Omit the times for all-day events.
- All dates are in GMT by default. Omit the trailing Z to use the user's local timezone, or use the ctz parameter to specify a custom timezone (see below).
details - Event description. Basic HTML is supported.
location – Event location.
ctz – Custom timezone from the tz database, for example: America/New_York
recur – Specify a recurring event with an RFC-5545 RRULE string. Example: recur=RRULE:FREQ=DAILY;INTERVAL=3. There's also an online generator to make those strings.
crm – Show as available/busy. Possible values are AVAILABLE, BUSY, and BLOCKING.
add – Semicolon-separated list of email adresses to add as event guests. If you set this parameter, it'll also add the user clicking the button as an event organiser.

Office 365 + Outlook Live

There is no official documentation, but I found some useful information here. Office 365 and Outlook Live use different base URLs:

Outlook Live: outlook.live.com/calendar/0/deeplink/compose?path=path=/calendar/action/compose&rru=addevent
Office 365: outlook.office.com/calendar/0/deeplink/compose?path=path=/calendar/action/compose&rru=addevent

The query parameters are the same:

subject (required) – Title
startdt (required) – Start date/time in ISO 8601 format (YYYY-MM-DDTHH:mm:SSZ). Omit the time for all-day events. All dates are in UTC by default. Omit the trailing Z to use the user's local timezone. To specify all-day events use the YYYY-MM-DD format.
enddt (required) – End date/time in ISO 8601 format (YYYY-MM-DDTHH:mm:SSZ). Omit the time for all-day events.
body – Description of the event
location – Location
allday – Is this an all-day event? true/false
to – Comma-separated list of emails of required attendees.
cc – Comma-separated list of emails of optional attendees

Microsoft Teams

There is official documentation, but I can't for the life of me get it to work. Maybe it's only designed to work from within a text chat on Teams? Who knows.

ICS

Most other calendar apps (like the Mac OS calendar and the Windows calendar app) support events in a file format called ICS. They look like this:

event.ics

BEGIN: VCALENDAR
VERSION: 2.0
BEGIN: VEVENT
DTSTAMP: 20220714T170000Z
DTSTART: 20220714T170000Z
DTEND: 20220714T190000Z
DESCRIPTION: Description
SUMMARY: Title
LOCATION: Location
END: VEVENT
END: VCALENDAR

The lines between BEGIN: VEVENT and END: VEVENT contain your event data. ICS has a lot of features, but the most useful ones for our scenario are:

SUMMARY – Title
DESCRIPTION – Description
LOCATION – Location
DTSTART – (required) Start date in the YYYYMMDDThhmmssZ format. All dates are in UTC by default, prepend a timezone name and omit the trailing Z to specify a local timezone: TZID=America/New_York:20220119T143000.
DTEND - (required) End date in the YYYYMMDDThhmmssZ format
DTSTAMP – (required) Calendar apps can use this parameter to resolve conflicting events. In our scenario, setting it to the same value as DTSTART seems to be enough.

You could make an ICS file server-side and point a link at it, but they're small enough to fit into a data URL:

<a
	href="data:text/calendar;charset=utf-8,BEGIN:VCALENDAR%0D%0AVERSION:2.0%0D%0ABEGIN:VEVENT%0D%0ADTSTAMP:20220714T170000Z%0D%0ADTSTART:20220714T170000Z%0D%0ADTEND:20220714T190000Z%0D%0ADESCRIPTION:The event description%0D%0ASUMMARY:The event title%0D%0ALOCATION:Location%0D%0ASTATUS:CONFIRMED%0D%0ASEQUENCE:0%0D%0AEND:VEVENT%0D%0AEND:VCALENDAR"
	>Download ICS</a
>

Demo

View on Codepen

Background

When you're building a website for a timed event like a talk or a workshop, you want to make it really easy for people to add your event to their own calendar. Once you get someone to do that, there's a pretty high chance they'll actually come to your event, which is why you're building the site in the first place.

An add-to-calendar button is a great way to do that. When people click it, it opens the "Add an Event" screen of their calendar app with all the event information already filled in, so all they need to do is hit "save". It doesn't replace showing the event information visually on your website, but it's a nice enhancement.

Different calendar apps have different standards (see above), so you'll have to compromise and probably show a few buttons at once, but the cost of that is relatively low because add-to-calendar links are HTML-only.

Notes

This is probably one of the rare cases where forcing the link to open in a new tab by adding target="_blank" is a good idea.
The ICS Spec