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.

Search...

Event parameters

Name(Value)Details
optionsStringified Array

Required

Options:Apple, Google, iCal, Microsoft365, MicrosoftTeams, Outlook.com, Yahoo
Array of options to use in the list.

You can also override the label per option here. Simply add a pipe between the option name and your label (e.g. "Google|My custom Google Label").
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.
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].

(If you are using the WordPress Plugin Shortcode, ']' would break your code. Instead of [*], you could also use {*} here.)

(Yahoo and Microsoft Teams are not fully supported and automatically transformed to plain text.)

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.

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.
endTimeString

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

Default:UTC
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.
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.
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
sequenceStringified bigInt

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|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 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|john.doe@gmail.com").
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.
datesStringified Array 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
  • location
  • status
  • sequence
  • uid
  • organizer
  • attendee


Example
recurrenceString

Options:
"RRULE:...";
daily, weekly, monthly, yearly
Defines recurring events.

This will deactivate the Yahoo and Microsoft options, since they do not support it at the moment (users could still use iCal in this case).
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_intervalStringified bigInt

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_countStringified bigInt 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.

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.
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".

Style parameters

Name(Value)Details
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, 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" to always open below the button.
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.
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" at the html or body tag and connect the button dynamically to the style of your website.
languageString

Options:ar, cs, de, en, es, 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.
customLabelsStringified Object For all text blocks, which are not already customizable via other options (like the word "Close"), 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 for the available keys. Mind to transform those keys to lower case strings without any whitespaces!
Any custom label will also override any translation.
You can use the same HTML pseudo tags as with the description option here.

Example

Additional parameters

Name(Value)Details
imagesStringified Array

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

Legal Notice | Privacy Policy | License | Help
© 2023 , Current Version: 2.2.4