Finally, a working Add-to-Calendar Button

7 min readNov 12, 2021

TLDR;

I’ve created a simple and free JavaScript snippet, which generates beautiful add-to-calendar buttons — and can be operated by basically anybody.

⚠️ Stop! There is a new version out!

Jump directly to the new V2 article at:

Implement an Add to Calendar Button in under 1 Minute

The all new version 2 of the popular open-source script!

medium.com

If you keep on reading, you will find out more about how such open source projects emerge and how it all started.

Background

I am getting married.

This is great news, but it comes with obligations and implications. One of them has been the creation of a website to inform guest about the date. Yes, we saved on the printed save-the-date card and wanted to use a website instead. And even if I’ve planned differently, I ended up coding the website myself from scratch — I am still asking myself “why the hell” every single day.

Anyhow, building this website, I needed to include a simple way for the users to add this event to their calendars.

Since I really did not want to spend too much time on this, I was looking for some easy to use script, package, whatsoever.

The Problem

I did not find anything, which matched my requirements.

Basically all free packages and code you find, is somehow outdated. It uses either some very old, no longer supported, schemes — or lacked of some basic functionality like creating an iCal/ics file.

On the other side, I found like 2000 references to addevent.com.

With “references”, I mean Google entries, but even more, codepens. There, many people (or fake people? 🙊) simply placed the code to integrate the addevent basic button. I am not sure why you would put that on codepen, but it is there.

The problem with addevent.com: It is pricey!

They have a free tier, but this limits the button calls to a fairly low number, which would not have worked — even for my little wedding event. So, I would even say it is completely useless, if not used for testing purposes only.

They have some additional cool features, but I basically do not need them — none of them. And I wanted to add a better UI/UX.

I’ve ended up building my own button … and thought … well, why not make an open source project out of it? So other people can benefit from my work and maybe even come up with new great ideas and want support the work. Plus, I get some karma points in return.

And that, my friends, is how open source is born in many cases (there are also others, but this might become another post some day).

Defining the requirements

Of course, I had some thing on my mind. I mean, those were the reason why I ended up with this situation in the beginning.

They would basically say:

Cool UI/UX
Works on Desktop and Mobile
Supports all modern calendars
Generates an iCal/ics file on the fly to support all other calendars (important part here: generate it and not require some file to be created manually before)

As always, when you start to build such a thing, a lot of additional requirements pop up.

When you decide to make it an open source project, you also need to think about other users (aka developers). How will they use your code? How skilled are they? What will be their expectations? Who are you building for?

To be honest, this was the hardest part!
I always have the rather unexperienced hobby-coder in mind, when I put something on the web. Those people should be able to use this code with ease. By simply adding some css and js files to their code. Without caring about anything else. It simply needs to work.
On the other side, to make it also appealing to other developers, it should comply with their daily work environments. I was thinking about modern JavaScript frameworks/libraries, like Angular or React.
So, it would be necessary to put this project on npm. And importing scripts into those projects works a little bit different than adding some stupid code snippet into an HTML page.
But anyhow, target audiences defined ✔️.

In terms of further requirements, you need to differentiate (looking at the target audiences) between functional and technical requirements.

On the functional side, all configuration should be easily doable by adding some simple JSON structure into any HTML structure. One could also see this as technical requirement, but for me, it is part of the UX somehow.

Looking at the events, one would want to use; they can start anytime, end anytime. They could be all-day or have specific times. But you also need to consider different time zones!
Adding an event’s subject, description, and location feels obvious.
But how about the add-to-calendar options? Maybe one does not want to offer Yahoo Calendar and keep it simple?
Regarding the interaction, I consider hover as a good trigger to open the dropdown. Maybe, in other cases, click would be the better trigger!
Last but not least, maybe a user does not want to make it a static event, but keep it flexible — by being always 10 days from the current day on?

I even came up with things like recurring events, and so on. I made the cut there and focused on single events 😋.

On the technical side, I felt that it should be documented at a very detailed level. Since I wanted to enable especially hobby coders to use it, this should come in handy. Personally, I hated it in my early days, when code was not documented (well or at all).
The code should be well structured, but still easily readable! This means that splitting it into too many abstract things might confuse people too much — even if it might be a cleaner code though.

Building it

Getting from the requirements to a working product was the rather easy part. And here we go … a working add-to-calendar button.
Free to use for everybody.
Working with modern browsers and calendars.
Generating iCal/ics files on the fly.
Usable by completely unexperienced people, as well as with a crazy Angular or React project (npm install add-to-calendar-button).

Shipping and where to get it

The project now lives within its GitHub repository at https://github.com/add2cal/add-to-calendar-button.
You can download it there — or fork it, if you know what this means (leave a star at your visit 😊)

On every version update, it also gets automatically deployed to npm at https://www.npmjs.com/package/add-to-calendar-button (thanks to GitHub Actions ♥️).

Demo

In case the gif above does not convince you, you can find more live examples at https://add-to-calendar-button.com/.
This page gets automatically generated by the current repository content —pure transparency 😉.

Features and Configuration

As stated before, you can easily adjust the button to your specific needs.

Let’s have a look at how to generate a button in the first place.
You only need to put a placeholder with the atcb class into your HTML code.

Mind that this changed with the latest version (V2)!!

<div class="atcb" style="display:none;">
  (...)
</div>

And then, of course, the css and js files (or the npm package — whatever works better for your project).

Within this placeholder, you can then define your configuration within a JSON structure.
See the following sample, but also the demo page for even more variations.

Mind that this changed with the latest version (V2)!!

<div class="atcb" style="display:none;">
  {
    "label":"Add to Calendar",
    "name":"Add the title of your event",
    "description":"A nice description does not hurt",
    "startDate":"02-21-2022",
    "endDate":"03-24-2022",
    "startTime":"10:13",
    "endTime":"17:57",
    "location":"Somewhere over the rainbow",
    "options":[
      "Apple",
      "Google",
      "iCal",
      "Microsoft365",
      "Outlook.com",
      "Yahoo"
    ],
    "timeZone":"Europe/Berlin",
    "timeZoneOffset":"+01:00",
    "trigger":"click",
    "iCalFileName":"Reminder-Event"
  }
</div>

If it does not show a button, mind the dev console. Maybe you misspelled something. The snippet will tell you.

Talking about features, there is a lot hidden implicitly within the project, but here are some hard facts:

Simple and convenient integration of one or multiple buttons — configure them directly within the HTML code.
Optimized UX (for desktop and mobile) — adjustable.
Beautiful UI (the best combined from experts around the world).
Up-to-date integration of all popular calendars: Google Calendar, Yahoo Calender, Microsoft 365 (and Outlook).
Automatically generated iCal/ics files (for all other calendars, like Apple).
Timed and all-day events.
Translatable labels and dynamic.
Support for SEO-friendly schema.org markup as an alternative to the default structure.
Well documented code, to easily understand the processes.

There is more to find out at the repository and, as always, by testing it yourself!

Feel free to use codepen for this; starting at https://codepen.io/jekuer/pen/eYEjxxz

Final words

That’s it.

At the moment, this project is going crazy after a very successful launch at ProductHunt (#1 Product of the Day), being celebrated by the ProductHunt team itself.