Please enable JavaScript to view this website.

Advanced Usage

On this page, we want to show you more special cases.
Additionally, you will learn how to customize even the smallest parts of the button.

We do not recommend to use those advanced options, if you are no experienced developer, since they can be really tricky and break the usual behavior!

Mind that if you did not check the "Examples" page before, you should go there first.

1. Using your own CSS styling

Built-in options

It seems obvious, but sometimes people jump directly into the ugly stuff, while there is a lot you can do with the included easy-to-use features.

Check the "Configuration" page for all available settings and functionalities.

The following examples use some of them to showcase the variety of the included styles.

<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  options="'Apple','Google','iCal'"
  buttonStyle="round"
  hideIconButton
  hideBackground
  label="My custom label"
  lightMode="bodyScheme"
></add-to-calendar-button>
<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  options="'Apple','Google','iCal'"
  buttonStyle="flat"
  hideIconList
  buttonsList
  hideBackground
  label="Flat and Singleton"
  lightMode="bodyScheme"
></add-to-calendar-button>
<add-to-calendar-button
  name="My awesome Event"
  startDate="2024-05-27"
  options="'Apple','Google','iCal'"
  startTime="10:10"
  endTime="10:40"
  timeZone="America/Los_Angeles"
  location="Fantasy Marketplace"
  buttonStyle="date"
  size="5"
  lightMode="bodyScheme"
></add-to-calendar-button>

Override styles

Generally, it is not possible to directly override the CSS style, since the button sits in its own ShadowDOM.
What you can do, however, is overriding some CSS variables, which are bound to the host (= the <add-to-calendar-button> tag).
You can simply provide the default ones via the "styleLight" attribute and the "dark mode" overrides via an additional "styleDark" attribute.

The available variables differ per selected button style. Check the respective css file in the repository (have a look at the "Global colors and shadows" section).

Mind that this is not working with the "none" button style or the atcb_action approach (see #10).

<add-to-calendar-button 
  styleLight="--btn-background: #2f4377; --btn-text: #fff; --font: Georgia, 'Times New Roman', Times, serif;"
  styleDark="--btn-background: #000;"
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  options="'Apple','Google','iCal'"
  hideIconButton
  lightMode="bodyScheme"
></add-to-calendar-button>

Load an external CSS file

Another approach you can use, would be to load an external CSS file. Provide the file with the "customCss" option and set the button style to "custom".
This file could, of course, also be within your application, but should not be bundled with other css. Additionally, it is not allowed to use a url path with "../" syntax due to security reasons. Absolute urls would be recommended.

Mind that in this case, you need to take care of all (!) elements.
It is recommended to copy a provided stylesheet from the repository and change what you want to change.

For this approach, you also need to make sure that your system allows to load external stylesheets (e.g. no blocking Content-Security-Policy rules).

In our example here, we keep it basic and only change the color again.

<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  options="'Apple','Google','iCal'"
  lightMode="bodyScheme"
  customCss="https://add-to-calendar-button.com/atcb.css"
  buttonStyle="custom"
  listStyle="modal"
></add-to-calendar-button>

Target elements via ::part

You can use the css ::part selector to directly style pre-selected elements from your regular css code.

The following elements are available for this approach:

  • atcb-button-wrapper
  • atcb-button
  • atcb-button-icon
  • atcb-button-text
  • atcb-list-wrapper
  • atcb-list
  • atcb-list-item
  • atcb-list-item-close
  • atcb-list-icon
  • atcb-list-text
  • atcb-modal-box
<add-to-calendar-button
  id="css-part-example"
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  options="'Apple','Google','iCal'"
  lightMode="bodyScheme"
></add-to-calendar-button>

<style>
  add-to-calendar-button#css-part-example::part(atcb-button) {
    background-color: #264f3c;
    color: #fff;
  }
</style>

Use a custom object as button

Last but not least, you could also stick to a provided style, but use your own triggering object.
Check the "10. Bring your own button" example at the bottom of this page for more details.

2. Enriching the event description

The event description does not need to be simple plain text!
You can use HTML special characters as well as specific formatting rules.

Those rules are set up as HTML pseudo tags, which get transformed automatically.
(If you are using the WordPress Plugin Shortcode, ']' would break your code. Instead of [*], you could also use {*} here.)
(Apple, Yahoo, and Microsoft Teams are not fully supported and automatically transformed to plain text, supporting only line breaks and hyperlinks.)

Suported tags:

  • [hr]
  • [p] ... [/p]
  • [br]
  • [strong] ... [/strong]
  • [u] ... [/u]
  • [i] ... [/i], [em] ... [/em]
  • [ul] ... [/ul], [ol] ... [/ol], [li] ... [/li]
  • [h*] ... [/h*] (← h1, h2, h3, ...)
  • [url] ... [/url]
    Define a URL text like this: [url]https://....|URL Text[/url]
<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  startTime="10:15"
  endTime="23:30"
  timeZone="America/Los_Angeles"
  options="'Apple','Google','iCal','Outlook.com','Microsoft 365','Microsoft Teams','Yahoo'"
  lightMode="bodyScheme"
  description="[p][strong]Check out[/strong] the maybe [u]easiest way[/u] to include Add to Calendar Buttons to your website! 🚀[/p][p]💻 [em]Visit the official website for more inspiration:[/em][br]&rarr; [url]https://add-to-calendar-button.com/|Click here![/url][/p]"
></add-to-calendar-button>

3. Offering a calendar subscription

You can also offer your users the option to subscribe to a calendar, instead of only saving static events.

To get this to work, you would simply need to set the public address (an .ics file) of the calendar as the "icsFile" option and set the "subscribe" option to true.

"name" is still required, but every other event parameter can be skipped in this case.
For Microsoft services, the "name" will be used as name for the calendar.
Mind that there won't be rich data for the subscribe option.
(If the user's browser does not recognize any installed calendar app, this might lead to a blank screen. The PRO version mitigates this with some explenatory middleware screen.)

<add-to-calendar-button
  name="[Test Subscription] Add to Calendar Button"
  subscribe
  icsFile="https://add2cal.github.io/ics-demo/demo-calendar.ics"
  options="'Apple','Google','iCal','Outlook.com','Microsoft 365','Microsoft Teams','Yahoo'"
  lightMode="bodyScheme"
></add-to-calendar-button>

4. Custom Text

You can change any text blocks.

For the button label you can simply specify the "label" option.

For all other text blocks (like the "Close" at the modal list type), you can specify the "customLabels" option.
There, you need to specify a JSON structure and define any text you want to override.
Check the atcb-i18n.js file at the repository for the available keys/options.
Any custom label will also override any translation.

(In case you are only looking for translating labels, check the "language" option instead!)

<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  startTime="10:15"
  endTime="23:30"
  label="Hit me to save!"
  options="'Apple','Google','iCal','Outlook.com','Yahoo'"
  listStyle="modal"
  customLabels='{"close":"Close the list again", "apple":"Apple is ok for me", "google":"Add to Google Cal", "outlookcom":"Use Outlook instead", "yahoo":"Yahoo, really?", "ical":"iCall ftw!"}'
  lightMode="bodyScheme"
></add-to-calendar-button>

5. Using advanced iCal properties

If you feel confident enough to mess with the rather unusual iCal settings, you can use the options "uid", "sequence", "created", "updated", "attendee", and "status" (TENTATIVE, CONFIRMED, CANCELLED).
They basically override the respective default values.

Mind that those options are only supported by the iCal and Apple calendar links!

To update an existing event (e.g. changing its status) by changing those properties, you would need to have a growing sequence number, newer "updated" date, same "created" date, the same "uid", and also the organizer field (name and email) set.

Some calendars only work with the "attendee" to be specified as well. And if your "update" to the event is not a status change to "CANCELLED", it is mandatory in all cases!
The attendee needs to be the person saving the event. If you know this, you can make use of this functionality. If not, we would not recommend it.

A. The following button adds an event via "REQUEST".
<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  startTime="10:15"
  endTime="23:30"
  timeZone="America/Los_Angeles"
  label="Add the event"
  description="A rather special example for customizing the Add to Calendar Button to its maximum.[br]Learn more at [url]https://add-to-calendar-button.com/[/url]"
  options="iCal"
  organizer="John Doe|john.doe@mail.com"
  uid="7060df05-7b3d-4baa-b215-689b85769e5b"
  sequence="1"
  created="20221201T103000Z"
  updated="20221205T154500Z"
  status="CONFIRMED"
  iCalFileName="Event-confirmed"
  lightMode="bodyScheme"
></add-to-calendar-button>
B. While this button cancels the event via the "CANCEL" method.
<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  startTime="10:15"
  endTime="23:30"
  timeZone="America/Los_Angeles"
  label="Cancel the event"
  description="A rather special example for customizing the Add to Calendar Button to its maximum.[br]Learn more at [url]https://add-to-calendar-button.com/[/url]"
  options="iCal"
  organizer="John Doe|john.doe@mail.com"
  uid="7060df05-7b3d-4baa-b215-689b85769e5b"
  sequence="2"
  created="20221201T103000Z"
  updated="20221218T154500Z"
  status="CANCELLED"
  iCalFileName="Event-cancelled"
  lightMode="bodyScheme"
></add-to-calendar-button>
Get blown away by the PRO offering

Want more functionality and way less trouble?

6. Set a custom ID

A generated button gets an ID assigned. This ID follows the scheme "atcb-btn-X", where "X" will be an ascending number.
The individual calendar links then get the button ID plus the calendar type assigned - like "atcb-btn-5-google".

You can override the automatically defined "X" at the button ID by defining a distinctive one with the "identifier" option.
This might help you to track any user interaction more precisely.

Mind that this ID needs to be unique and may not be used at any other element!

It behaves a little different, if you are using the custom atcb_action function, where the script might take the triggering element's id first, before falling back to the described scheme.

<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  startTime="10:15"
  endTime="23:30"
  timeZone="America/Los_Angeles"
  options="'Apple','Google','iCal','Outlook.com','Microsoft 365','Microsoft Teams','Yahoo'"
  identifier="my-custom-id"
  lightMode="bodyScheme"
></add-to-calendar-button>

7. Tracking

We keep track of any action happening with a button.
You can read this data in 2 ways.

  1. Observe the atcb-last-event attribute, which gets added to every button. It holds the last event and respective trigger (schema: "EVENT:TRIGGER"; example: "openList:atcb-btn-1").
  2. Access the Data Layer.

We are pushing the events directly into the Data Layer, which can be read, for example, with the Google Tag Manager and Google Analytics.

Available Events:

  • initialization
  • openList
  • closeList
  • openCalendarLink
  • openSingletonLink
  • openSubEventLink
  • success

(You can try this by playing with a button on this site and putting "dataLayer" into the JavaScript console.)

8. Use the browser's time zone

There are some really rare cases where you might not have an event with a specific place and time, but rather a time bound to the user's individual time zone.
For example offering an event, which should remind the users at 8am to brush their teeth.

In those cases, you could set the "timeZone" option to "currentBrowser".
The event's time will then be automatically adjusted for each user based on the individual time zone.

<add-to-calendar-button
  name="[Reminder] Test the Add to Calendar Button"
  startDate="2024-05-27"
  startTime="10:00"
  endTime="11:00"
  timeZone="currentBrowser"
  location="World Wide Web"
  description="Check out the maybe easiest way to include Add to Calendar Buttons to your web projects:[br]→ [url]https://add-to-calendar-button.com/|Click here![/url]"
  options="'Apple','Google','iCal'"
  lightMode="bodyScheme"
></add-to-calendar-button>

9. WebView

On mobile devices, applications, which are using the "WebView", have problems with how we generate and deliver the .ics files on the fly.
Therefore, we catch those cases, copy the data url to the user's clipboard, and show a short guide on how to proceed.

Since this is the best practice for all websites and web apps, it might not be, if you are building your own native/hybrid app where you have control over the WebView settings.

While this would still break the dynamic generation of the .ics file, you could at least deliver existing external ics files directly.
In this case, you could deactivate the described workaround with the "bypassWebViewCheck" option.

Please make sure that the following applys to your project!

  • You are developing your own native/hybrid app.
  • You are opening the device's default browser instead of using any in-app WebView.
  • You have a distinctive .ics file on some server and can refer to it via the "icsFile" option.
(The button below should not fire within an in-app WebView like at the Instagram native app - but it would in your app.)
<add-to-calendar-button
  name="Title"
  startDate="2024-05-27"
  startTime="10:15"
  endTime="23:30"
  options="iCal"
  icsFile="https://add-to-calendar-button.com/demo-event.ics"
  bypassWebViewCheck
  lightMode="bodyScheme"
></add-to-calendar-button>

10. Bring your own button

For those who want to go fuc**** crazy custom, we also provide the option to trigger the calendar links list manually.
This provides you with the option to use anything as your button or even trigger it programmatically.

Theoretically, you do not need to provide a button element. However, it is recommended to do so, since it will optimize the user experience a lot (like focusing the element on closing the modal, etc.).
If you do not provide a specific button, the list will automatically show as modal. If provided, you can opt for the overlay-dropdown list style via the listStyle option (mind that all other options are not supported in the atcb_action case). The modal style is strongly recommended.

Step 1: Import

If you use the script via CDN, you can skip this step.
If you use the script as npm package, you would first need to import the "atcb_action" functionality. Simply change the import statement to the following:

import { atcb_action } from "add-to-calendar-button";

Step 2: Config and trigger

Secondly, you would need to define the config and the trigger.
This might differ a lot based on your environment. You are the expert there.

In the example we use a quite simple button for the demonstration.

<button id="my-default-button">Click here</button>

<script type="application/javascript">
  const config = {
    name: "[Reminder] Test the Add to Calendar Button",
    description: "Check out the maybe easiest way to include Add to Calendar Buttons to your web projects:[br]→ [url]https://add-to-calendar-button.com/|Click here![/url]",
    startDate: "2024-05-27",
    startTime: "10:15",
    endTime: "23:30",
    options: ["Google", "iCal"],
    timeZone: "America/Los_Angeles"
  };
  const button = document.getElementById('my-default-button');
  if (button) {
    button.addEventListener('click', () => atcb_action(config, button));
  }
</script>

11. Loading strategies

First things first:
Wherever possible, we load the script asynchronously, so it will not block the rendering of your page.
However, if you include it as a ES module, this behavior usually changes.
Besides some JavaScript frameworks offering other tricks to load components asynchronously, you can try the following to optimize the loading behavior and bundle size.

Unfortunately, we cannot offer any easy tree-shaking solution, as this contradicts the way we are building the script - being a flexible web component, which can adapt on runtime.

The ES package comes in 4 flavors:

  1. Default: Includes everything and therefore reduces the risk of failure.
  2. no-pro: This is basically the default, if you are not using the of the script.
  3. unstyle: This is the default, but without integrated css (style).
  4. no-pro-unstyle: No integrated css, no PRO functionalities.

To reduce the bundle size, you can use the unstyle version with

import 'add-to-calendar-button/unstyle'
and add the css manually to your project via the customCss option.
For the css file, you can make use of the jsDelivr CDN - find possible files at jsdelivr.
This, of course, makes changing the style more difficult and adds an additional request to the network, but would reduce the bundle size by ~ 30%.
In the end, it depends on your project and strategy, which version is the best for you.

Get blown away by the PRO offering

Discover the PRO offering

More functionality (like RSVP) and way less trouble thanks to managed ics file hosting, no-code customization, and more.


Legal Notice | Privacy Policy | License | Help
© 2024 , Current Version: 2.6.15