Add to Calendar Button Configuration

If you are using the PRO service, you can use the "prokey" attribute to connect the button to a specific event of yours.
In this case, no other parameters need to be defined in the code, since this is 100% managed at the Add to Calendar PRO admin panel.

If an event group is configured for both subscription and an event list, it defaults to the subscription button. Use this attribute to show the event list instead.

Optional settings for group-overview:

• years-only (Boolean): Hides the month selector and shows all events for the selected year.
• type (String): list (default), cards, or compact.
• from (String): UTC ISO datetime limiting the lower end. It cannot be earlier than January 1 of the previous year.
• to (String): UTC ISO datetime limiting the upper end. It cannot precede from.
• no-details (Boolean): Opens the calendar options modal instead of linking to its landing page.
• no-add (Boolean): Disables all event interactions. Entries have no landing page link, calendar action, or add badge, regardless of the other settings.
• custom-domain (String; Hostname, like events.acme.com): Uses this domain, for landing page links. The domain must also be configured in Add to Calendar PRO.
• add-via-list (Boolean): Adds a subtle calendar-add badge. With no-details, it is part of the event link and opens the calendar options together with the rest of the entry.

The title of your event.

Should be a rather short string.
In case you set the "dates" parameter (multi-date), the name is still required. It then acts as fallback and name for the event series.
In the subscription case, the name would be used as calendar name for Microsoft services.

Supports HTML pseudo tags for formatting: [url], [br], [hr], [p], [strong], [u], [i], [em], [li], [ul], [ol], [h*] (like h1, h2, h3, ...).
Define a link text with the following schema: [url]https://....|URL Text[/url].

(In case of compatibility issues, you can use curly {} instead of square [] brackets here.)

(Apple, Yahoo, and Microsoft Teams are not fully supported and automatically transformed to plain text, supporting only line breaks and hyperlinks.)

Example

A date needs to be formatted as YYYY-MM-DD as specified with ISO-8601.

You can use the magic word "today" to dynamically set the current day. Adding "+5" at the end would automatically add 5 days to the calculated date.

Unofficially, something like "YYYY-MM-DDTHH:MMZ" would also work.

Example

If not set, the event will be defined as "all-day".

A date needs to be formatted as YYYY-MM-DD as specified with ISO-8601.

If there is no end-date set, it is assumed that it is the same as start-date. You can use the magic word "today" to dynamically set the current day. Adding "+5" at the end would automatically add 5 days to the calculated date.

Unofficially, something like "YYYY-MM-DDTHH:MMZ" would also work.

If not set, the event will be defined as "all-day".

It is not required, but recommended to add a time zone.
Find a list of them at Wikipedia.

You can use "currentBrowser" as value to dynamically use the time of the user's browser. Use this with caution, since it would mean that the time for the event will differ per user, which should not be the usual case.
A time zone only comes into play, when start-time and end-time are defined.

This option would transform time and time zone to the respective user's settings.

If you set this option to "true", the time would be transformed to the user's time zone.
This is different to the artificial "browserTime" time zone, which would only transform the time zone, but not the time itself.
Use with caution, as manipulating the time zone per user can have unwanted side effects. This usually should be done by the user's calendar app!

Can be anything.

If it is a URL, the event will be classified as "online event" via the schema.org declaration.
An online event is not showing up on the date button. Additionally, the time on this button type will then be converted to the user's time zone (will also be done, if location is "Global", "Worldwide", or "Online").

Can be used to manage changes of an event as it is specified within the iCalendar specifications RFC5545.

Example

Needs to be a positive integer number.
Needs to grow when you make changes to the event.

Example

Per default, the event will be marked as busy/free/available based on the user's calendar settings.
For Apple, iCal, and Google, you can force this by using the setting availability with options "busy" or "free".

The unique ID of the event as it is used within the iCal file.

May only contain alpha, digits, and dashes; and be less than 255 characters.
A hex-encoded random Universally Unique Identifier (UUID) is recommended.

Use the schema "NAME|EMAIL" (e.g. "John Doe|john.doe@gmail.com").

The organizer will appear within the schema.org rich data as well as the iCal file.
Setting this option will also change how ics files (iCal) are processed. Calendars will no longer simply save the event, but look at it as an event invitation one can accept or decline.

Example

Use the schema "NAME|EMAIL" (e.g. "John Doe|john.doe@gmail.com"), or email only as the name is optional.
With setting this option, you would be able to update an event in a user's calendar, if this user loads the new iCal file as well.

Only 1 attendee can be specified
This attendee needs to be the person saving the event.
If you do not have this information, do not use this option!

When you specify an attendee, you also need to specify an organizer.

If you want to define an event series, you can use the dates object.

It basically holds the same date structure as the root level, but enables you to define multiple events. Root level values override values in the dates object - except for the name if there are multiple dates (then, the root name will become the title of the event series). There is one special case with the "UID", which only uses the root level information for the first sub-event (since it needs to be unique). All subsequent sub-events will receive randomly generated new UIDs.

Attributes per sub-event block:

• name
• description
• start-date
• start-time
• end-date
• end-time
• time-zone
• use-user-tz
• location
• status
• sequence
• availability
• uid
• organizer
• attendee
• most ics options - see further down

Example

Defines recurring events.

This will deactivate the Yahoo and Microsoft (and Google at iOS) options, since they do not support it at the moment (users could still use iCal in this case). If no option is left then, iCal will be set as fallback.
Mind that it is not possible to use more than 1 dates (dates option) and recurrence.

You can use any valid RRULE except for BYHOUR, BYMINUTE, and BYSECOND to define the respective rule (click here for a generator).

As an alternative to the RRULE, you could also specify the following more specific reccurence settings, which will then generate the RRULE for you in the background (see next parameters).
In this case, for the "recurrence" field, you would define the frequency (daily, weekly, monthly, yearly) instead of the RRULE.

Example

Defines the interval between iterations.
"3" would mean "every third".

Defines an end date.
We automatically convert this into the correct COUNT value as UNTIL is not supported by all applications.

Defines an upper limit of repetitions.
If recurrence-until and recurrence-count are given, whatever comes first overrides the other. If none are given, it would repeat indefinitely.

Defines the weekdays (MO, TU, WE, TH, FR, SA, SU), where the even occurs (if, for example, it is bound to Tuesday instead of the 24th).
Requires a weekly frequency.
Can be enriched with a number to specify something like the 3rd Monday (3MO).
Can be multiple, comma separated.

Use this instead of the "byDay" option, if you want use a numbered day (1, 2, ... 31) instead of a weekday.
Requires a monthly frequency.
Can be multiple, comma separated.

Defines the months (1, 2, 3, ... 12), where the event should happen.
Requires a yearly frequency.
Can be multiple, comma separated.

Specify a specific weekday as start of the week.

As an alternative to providing a specific predefined event, you can also host a calendar and offer it for subscription (requires a hosted calendar).
To offer the subscription via the button, you need to also specify the ics-file option.

"Name" and "start-date" would be still required for organizational purposes, but every other event parameter can be skipped in the subscription case.
For Microsoft services, the "Name" will be used as name for the calendar.
Microsoft Teams is not yet supported, while Yahoo is no longer supported. Both will be automatically disabled. The same applies to other Microsoft services on mobile devices.

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.

Example

The iCal/ics file gets created dynamically.
This has some drawbacks as it might be blocked in some rare cases.
With this option, you can redirect to an existing ics file instead.

In the subscription case, you need to define the external calendar here.

If you have multiple dates and an organizer or status set, you would need to prepare multiple ics files, where the one for the first date is specified here, while all subsequent dates look for a file with the same name and a number (starting with 2) appended (e.g. "event-2.ics").

If you want to define a specific name for any generated ics file (iCal), you can specify it via the ical-file-name option.

Adds a reminder alarm. Set the minutes before the event start (like "30") or a raw ISO 8601 duration (like "-PT1H").

Attaches a canonical link (the URL property) to the event. Needs to be a valid http(s) url.

Tags the event with a comma-separated list of categories.

Sets the event classification.

Sets the priority from 0 (undefined) over 1 (highest) to 9 (lowest).

Adds geo coordinates. Combined with the regular "location" option, Apple Calendar renders its map preview.

Attaches files by url (a comma-separated list of http(s) urls) - like an agenda PDF or a ticket.

Excludes dates from a recurring event (a comma-separated list of dates). Requires the "recurrence" option and is the only one of these options that cannot be set per date entry.

The "Created" field in the iCal file would default to the time the file gets generated and downloaded.
Use this option, if you want to define a specific static timestamp instead.

Should be a UTC timestamp like "20231201T103000Z".

The "Updated" field in the iCal file would default to the time the file gets generated.
Use this option, if you want to define a specific static timestamp instead.

Should be a UTC timestamp like "20231201T103000Z".

Array of options to use in the list.

If you only specify 1 calendar type, the button would show the calendar's icon instead of the default one and redirect directly instead of opening a list (singleton case).

Some options might be dynamically excluded based on other settings!
"ical" will be replaced by "apple" on iOS devices.

You can specify a different set of options for mobile devices via the options-mobile option. If you also set the options-ios option, this will account for iOS (not Mac!), while options-mobile accounts for Android and other mobile devices.

There are multiple integrated button styles, which also affect a lot of other parameters.
We recommend to play around with them in order to find out how they behave in detail.

"none" would simply load no css style at all, while "custom" requires an external css file specified with the "custom-css" option.

Only the default style is part of the script itself - every other style loads automatically on demand (a few KB), or fetch-free via import 'add-to-calendar-button/styles/3d' and the like when bundling. To register all styles at once, use import 'add-to-calendar-button/styles/all'. See the "style-source" and "load-all-styles" options for more control.

Renders the button inline instead of the default block style.

You can load an external css file instead of using and customizing the integrated one.
Define the url of the file here and set the button-style option to "custom".
Mind that custom css does not get loaded on SSR!

Example

Overrides the base url from which on-demand assets (button styles beyond the default, language packs beyond English) are loaded.

By default, they load from wherever the script itself is hosted. Set this option if you self-host the script in an exotic setup or want to serve the assets from a dedicated location. The url should point at the directory that contains the styles/ and locales/ folders.

Prefetches every button style delta on initialization.

Only useful when you switch the "button-style" at runtime (for example in a live theme switcher) and want the change to apply without any network delay.

This option only works when using the button via a script tag, not via the npm package. With npm, import the required style modules instead - or import 'add-to-calendar-button/styles/all' to register every style at once.

Renders one button per calendar type instead of the button + list.

This option overrides the text at the button.

The dropdown or overlay list unfolds on hover per default in most cases.
If you want it to get triggered on click, you can specify this with this option.

The calendar link list can be rendered as dropdown, overlay, or modal.

The dropdown style also considers the position of the button on the screen and shows the list automatically above or below the button. Use "dropdown-static" or "dropup-static" to always open below or above the button.

This option renders the dropdown together with the button above everything else - similar to the modal option.
This can be useful, if your layout and HTML structure conflicts with the default, where the dropdown gets rendered next to the button.

However, it comes with some small performance drawbacks.

With this option, you get a fully transparent background instead of the darker blurry one.

This option hides the icon at the button.

This option hides the icons at the calendar link list.

This option hides the heading icon at any info modal.

This option hides the text label at the button.

This option hides any text at the calendar link list.

Clicking a calendar link marks the event as "saved" by adding a checkmark icon.
This is not the case, if the button's text labels are turned off, you use the buttons-list option, or when using atcb_action.
Set this option to disable it in all other cases too.

This option specifies what happens, if an event is overdue.
Setting it to "disable" will disable the button, while "hide" will completely hide it. In both cases, the user can no longer save the event.

Mind that with recurring events, this will not get triggered!

Specify a number between 0 and 10 to scale the button.

You can define 1 number like "5" or up to 3 values like "8|6|4", where the first one will apply to large, the second to medium, and the third to small screens.
If you provide two, it will be for large and medium+small screens.

Each button comes with a dark and light mode.

Set the option light-mode to "dark" or "light" explicitly, or use "system" to automatically adapt to the user's default setting.
You can also use "bodyScheme" to look for the class "atcb-dark" (or "dark") at the html or body tag and connect the button dynamically to the style of your website.

Selects included translations. Base languages use ISO 639-1 codes and RTL is supported. English is built in; others load on demand or via locale imports. Full locales such as en_GB prefer a regional pack and regional date formatting.

Overrides all text blocks using a JSON object with flattened locale keys such as label.addtocalendar; custom labels override translations and support the description pseudo tags. Renamed keys are documented in the locale files.

Example

You can override global css variables for the button. See the CSS files in the repository. Example: style-light="--btn-background: #2f4377; --btn-text: #fff; --font: Georgia, 'Times New Roman', Times, serif;". style-light is the default; define style-dark for dark mode.

You can override global css variables for the button. Find out what you can change by having a look at the top section at a respective css file in the repository.

Images enrich schema.org data. Define at least one absolute URL with 720px width; ideally three 1920px images in 1x1, 4x3, and 16x9.

If you set at least a name, start-date, and location, the script automatically generates schema.org rich data when rendering a button. Setting this option would disable the feature.

Each generated button and calendar link has a speaking ID for tracking: "atcb-btn-IDENTIFIER" or "atcb-btn-IDENTIFIER-google". IDENTIFIER defaults to an ascending number and can be overridden (unique, no special characters).

On iPhone WebViews, ics downloads cannot be offered directly, so instructions are shown. Bypass only in your own app when downloads open in the default browser and ics-file is explicitly provided.

Per default, there is a slight branding to support this free open-source project. This option removes it while complying with the license.

Adds a "nonce" attribute with the provided value to all inline script and style tags for strict Content-Security-Policy environments.

Use this attribute to force a re-rendering of the button by counting its value 1 up.

With this option enabled, any setting would override its corresponding one from the PRO app. Use with caution, as this can lead to inconsistencies across systems!

Setting this option would put any misconfiguration into the browser's JavaScript console and also render an error instead of the calendar. Helpful while implementing the button for the first time.