Configuration

The following list holds all potential attributes to set up and customize your next Add to Calendar Button.

Check the Demo to play with most of them and explore the examples pages for more extensive descriptions for specific cases.

Event parameters

Name(Value)Details
proKeyString 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.
nameString

Required
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.
descriptionString 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
startDateString

Required, if not using "dates" or "subscribe" option

YYYY-MM-DD
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
startTimeString

HH:MM
If not set, the event will be defined as "all-day".
endDateString

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

If there is no endDate set, it is assumed that it is the same as startDate. 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.
endTimeString

HH:MM
If not set, the event will be defined as "all-day".
timeZoneString

Default:GMT
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 startTime and endTime are defined.
useUserTZBoolean

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

If you set this option to "true", the time zone would be ignored and 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!
locationString

Required, if you want Schema.org rich data
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").
statusString

Options:TENTATIVE, CONFIRMED, CANCELLED

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

Example
sequenceNumber

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

Example
uidString

XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

Default:Randomly generated
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.
organizerString

NAME|EMAIL
Use the schema "NAME|EMAIL" (e.g. "John Doe|[email protected]").

The organizer will appear within the schema.org rich data as well as the iCal file.
Setting this option will also change the style of the iCal information from being an event to simply save to an event invitation one can accept or decline.

Example
attendeeString

NAME|EMAIL
Use the schema "NAME|EMAIL" (e.g. "John Doe|[email protected]"), 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.
datesArray of Objects If you want to define an event series, you can use the dates object.

It basically holds the same information as the top level, but enables you to define multiple events. Except for date and time information, all other attributes, if not provided in the dates object, use the top level information as fallback. There is one special case with the "UID", which only uses the top 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
  • startDate
  • startTime
  • endDate
  • endTime
  • timeZone
  • useUserTZ
  • location
  • status
  • sequence
  • availability
  • uid
  • organizer
  • attendee


Example
recurrenceString

Options:
"RRULE:...";
daily, weekly, monthly, yearly
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 to define the respective rule (click here for a generator ).
Mind that the startDate needs to be valid within the given recurrence ruleset!

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
recurrence_intervalNumber

Default:1
Defines the interval between iterations.
"3" would mean "every third".
recurrence_untilString Defines an end date.

Mind that this does not work in many applications! Rather use the count option.
recurrence_countNumber 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.
recurrence_byDayString 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.
recurrence_byMonthDayString 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.
recurrence_byMonthString

Options:1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12
Defines the months (1, 2, 3, ... 12), where the event should happen.
Requires a yearly frequency.
Can be multiple, comma separated.
recurrence_weekstartString

Options:MO, TU, WE, TH, FR, SA, SU

Default:MO
Specify a specific weekday as start of the week.
availabilityString

Options:busy, free

Default:Default setting at the user's calendar
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".
subscribeBoolean

Default:False
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 icsFile option.

"Name" and "startDate" 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 and will be automatically disabled. Same applies for 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
icsFileString

URL
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").
iCalFileNameString

Default:event-to-save-in-my-calendar
If you want to define a specific name for any generated ics file (iCal), you can specify it via the iCalFileName option.
createdString

YYYYMMDDTHHMMSSZ

Default:Time the file gets downloaded
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".
updatedString

YYYYMMDDTHHMMSSZ

Default:Time the file gets downloaded
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".
Get blown away by the PRO offering

Want more functionality and way less trouble?

Layout parameters

Name(Value)Details
optionsArray

Options:Apple, Google, iCal, Microsoft365, MicrosoftTeams, Outlook.com, Yahoo
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 optionsMobile option. If you also set the optionsIOS option, this will account for iOS (not Mac!), while optionsMobile accounts for Android and other mobile devices.
buttonStyleString

Options:default, 3d, flat, round, neumorphism, text, date, custom, none

Default:default
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 "customCss" option.
inlineBoolean

Default:False
This option would render the button inline instead of the default block style.

Example
customCssString

URL
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 buttonStyle option to "custom".

Example
buttonsListBoolean

Default:False
Activating this option would render one button per calendar type instead of the button + list.

Example
labelString

Default:Add to Calendar
This option overrides the text at the button.
triggerString

Options:hover, click

Default:hover
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.
listStyleString

Options:dropdown, dropdown-static, dropup-static, overlay, modal

Default:dropdown
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.
forceOverlayBoolean

Default:False
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.
hideBackgroundBoolean

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

Default:False
This option hides the icon at the button.
hideIconListBoolean

Default:False
This option hides the icons at the calendar link list.
hideIconModalBoolean

Default:False
This option hides the heading icon at any info modal.
hideTextLabelButtonBoolean

Default:False
This option hides the text label at the button.
hideTextLabelListBoolean

Default:False
This option hides any text at the calendar link list.
hideCheckmarkBoolean

Default:False
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 buttonsList option, or when using atcb_action.
Set this option to disable it in all other cases too.
pastDateHandlingString

Options:none, disable, hide

Default:none
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!
sizeString

X|X|X

Default:6|6|6
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.
lightModeString

Options:system, dark, light, bodyScheme

Default:light
Each button comes with a dark and light mode.

Set the option lightMode 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.
languageString

Options:ar, cs, de, en, es, et, fa, fi, fr, hi, id, it, ja, ko, nl, no, ro, pl, pt, sv, tr, vi, zh

Default:en
If you want to have the text blocks in another language than English, you can use the included translations (i18n).

Simply set one of the supported languages as ISO 639-1 code .
Also supports Right-to-Left (RTL) with Arabic & Persian.
customLabelsObject You can alter all text blocks via 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 for the available keys. Any custom label will also override any translation.
For text blocks, you can use the same HTML pseudo tags as with the description option here.

Example
styleLightString 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 .

Example: styleLight="--btn-background: #2f4377; --btn-text: #fff; --font: Georgia, 'Times New Roman', Times, serif;"

The styleLight option acts as default. To override dark mode variables, also define styleDark (see below).
styleDarkString 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 .
Get blown away by the PRO offering

Want more functionality and way less trouble?

Additional parameters

Name(Value)Details
imagesArray

URLs
Images are used to enrich the rich data and therefore how an event might appear, for example, at the Google search results.
It is recommended to define at least 1 image via an absolute url with at least 720px width.
Ideally, you specify 3 images with a width of 1920px each. One with an aspect ration 1x1, one with 4x3, and one with 16x9. If not set, a default fallback image will be used.
hideRichDataBoolean

Default:False
If you set at least a name, startDate, and location, the script automatically generates schema.org rich data when rendering a button.
Setting this option would disable the feature.
identifierString

Default:Ascending number
Each generated button and calendar link has a speaking ID to be used for any tracking methods.
Scheme: "atcb-btn-IDENTIFIER" or "atcb-btn-IDENTIFIER-google" (for the Google option) respectively.
The IDENTIFIER will be an ascending number, but can be overridden by providing the option "identifier" (no special characters allowed; needs to be unique).
bypassWebViewCheckBoolean

Default:False
For users loading the button on their iPhone within a WebView environment (e.g. the Instagram Browser), we are not able to directly offer the ics file for download.
Therefore, we show a small instruction note on how to do it instead.
If you are using the button in your own app, where you actively allow the download of ics files in the default browser and are also providing the file explicitely with the icsFile option, you can bypass this workaround with the option bypassWebViewCheck.
hideBrandingBoolean

Default:False
Per default, there is a slight branding.
This is a small support for this free open-source project.

If you do not want to support this project, you can set this option to remove the branding and still comply with the underyling license.
instanceNumberUse this attribute to force a re-rendering of the button by counting its value 1 up.
proOverrideBoolean

Default:False
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!
debugBoolean

Default:False
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.

Let's directly test most of the options at our playground!

Start playing

Or explore more specific examples.

Start exploring

For the edge cases, you can check the "danger zone".

Advanced Usage
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.7.3