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.
To specify a boolean value within the HTML custom element, you would only add the name as attribute.
Not setting it would automatically reflect to "false". As an alternative, you could also always write it as a string like attributeName="true".
Event parameters
| Name(Value) | Value | Details |
|---|---|---|
| proKey | String | 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. |
| name | String 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. |
| description | String | 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 |
| startDate | String 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 |
| startTime | String HH:MM | If not set, the event will be defined as "all-day". |
| endDate | String 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. |
| endTime | String HH:MM | If not set, the event will be defined as "all-day". |
| timeZone | String 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. |
| useUserTZ | Boolean 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! |
| location | String 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"). |
| status | String 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 |
| sequence | Number Default:0 | Needs to be a positive integer number. Needs to grow when you make changes to the event. Example |
| uid | String 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. |
| organizer | String 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 |
| attendee | String 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. |
| dates | 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:
Example |
| recurrence | String 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_interval | Number Default:1 | Defines the interval between iterations. "3" would mean "every third". |
| recurrence_until | String | Defines an end date. Mind that this does not work in many applications! Rather use the count option. |
| recurrence_count | Number | 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_byDay | String | 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_byMonthDay | String | 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_byMonth | String 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_weekstart | String Options:MO, TU, WE, TH, FR, SA, SU Default:MO | Specify a specific weekday as start of the week. |
| availability | String 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". |
| subscribe | Boolean 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 |
| icsFile | String 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"). |
| iCalFileName | String 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. |
| created | String 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". |
| updated | String 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". |
Want more functionality and way less trouble?
Discover the PRO offeringLayout parameters
| Name(Value) | Value | Details |
|---|---|---|
| options | Array 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. |
| buttonStyle | String 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. |
| inline | Boolean Default:False | This option would render the button inline instead of the default block style. Example |
| customCss | String 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 |
| buttonsList | Boolean Default:False | Activating this option would render one button per calendar type instead of the button + list. Example |
| label | String Default:Add to Calendar | This option overrides the text at the button. |
| trigger | String 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. |
| listStyle | String 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. |
| forceOverlay | Boolean 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. |
| hideBackground | Boolean Default:False | With this option, you get a fully transparent background instead of the darker blurry one. |
| hideIconButton | Boolean Default:False | This option hides the icon at the button. |
| hideIconList | Boolean Default:False | This option hides the icons at the calendar link list. |
| hideIconModal | Boolean Default:False | This option hides the heading icon at any info modal. |
| hideTextLabelButton | Boolean Default:False | This option hides the text label at the button. |
| hideTextLabelList | Boolean Default:False | This option hides any text at the calendar link list. |
| hideCheckmark | Boolean 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. |
| pastDateHandling | String 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! |
| size | String 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. |
| lightMode | String 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. |
| language | String 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. |
| customLabels | Object | 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 |
| styleLight | String | 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). |
| styleDark | String | 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 . |
Want more functionality and way less trouble?
Discover the PRO offeringAdditional parameters
| Name(Value) | Value | Details |
|---|---|---|
| images | 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. |
| hideRichData | Boolean 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. |
| identifier | String 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). |
| bypassWebViewCheck | Boolean 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. |
| hideBranding | Boolean 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. |
| cspnonce | String | This will add an attribute "nonce" with the provided value to all inline script and style tags. Useful for strict Content-Security-Policy environments. |
| instance | Number | Use this attribute to force a re-rendering of the button by counting its value 1 up. |
| proOverride | Boolean 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! |
| debug | Boolean 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. |
Discover the PRO offering
More functionality (like RSVP) and way less trouble thanks to managed ics file hosting, no-code customization, and more.