Add to Calendar Button – JavaScript Calendar Links

Add-to-Calendar Button is a JavaScript web component for creating event buttons that open Google Calendar, Apple Calendar, Outlook, Microsoft 365, Microsoft Teams, Yahoo Calendar, or an iCal file.

It works as a custom <add-to-calendar-button> element in HTML and also exposes a JavaScript API for custom triggers.

Features

• Calendar links for Apple, Google, iCal, Microsoft 365, Microsoft Teams, Outlook.com, and Yahoo.
• Timed, all-day, recurring, and multi-date events.
• Calendar subscription links through an external ICS calendar.
• Built-in button styles, dark mode, custom CSS variables, external CSS, and ::part styling hooks.
• Localized labels with RTL language handling.
• Generated Schema.org event data and configurable ICS metadata.
• Custom trigger support through atcb_action().
• Tracking data through the element attribute and browser data layer.

How to use it

1. Install Add-to-Calendar Button

Load the latest JavaScript from a CDN.

<script src="https://cdn.jsdelivr.net/npm/add-to-calendar-button@3" async defer></script>

Or install & import it via NPM

npm install add-to-calendar-button

import 'add-to-calendar-button';

Import necessary styles and languages.

import 'add-to-calendar-button';
import 'add-to-calendar-button/styles/3d';
import 'add-to-calendar-button/i18n/de';

2. Create a basic Add to Calendar button

<add-to-calendar-button
  name="Launch Party"
  start-date="2026-10-15"
  start-time="18:00"
  end-time="20:00"
  time-zone="America/Los_Angeles"
  location="123 Demo Street"
  options="'apple','google','ical','ms365','msteams','outlookcom','yahoo'"
></add-to-calendar-button>

3. Create an all-day event

Omit start-time and end-time for an all-day event.

<add-to-calendar-button
  name="Conference Day"
  start-date="2026-10-20"
  end-date="2026-10-20"
  options="'apple','google','ical','outlookcom'"
></add-to-calendar-button>

4. Create a recurring event

<add-to-calendar-button
  name="Weekly Standup"
  start-date="2026-10-05"
  start-time="09:00"
  end-time="09:30"
  time-zone="America/New_York"
  options="'apple','google','ical'"
  recurrence="weekly"
  recurrence-by-day="MO"
  recurrence-count="12"
></add-to-calendar-button>

5. Open the menu on click

<add-to-calendar-button
  name="Product Demo"
  start-date="2026-10-12"
  options="'google','outlookcom'"
  trigger="click"
></add-to-calendar-button>

6. Use your own trigger button

Use atcb_action() when your project needs a custom button or a programmatic trigger. JavaScript configuration objects use camelCase.

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

const config = {
  name: 'Launch Party',
  startDate: '2026-10-15',
  startTime: '18:00',
  endTime: '20:00',
  timeZone: 'America/Los_Angeles',
  options: ['google', 'ical']
};

const button = document.querySelector('#calendar-button');
button.addEventListener('click', () => atcb_action(config, button));

Full configuration options

Boolean HTML options can be written as bare attributes, such as inline or subscribe. The JavaScript configuration form uses camelCase equivalents.

Event parameters

Attribute	Type / Default	Description
name	String, required	Event title. It also acts as the series name for multi-date events.
description	String	Event description. Pseudo tags such as [p], [strong], [br], lists, headings, and [url] are available.
start-date	String, YYYY-MM-DD	Start date. Required unless dates or subscription mode supplies the date context.
start-time	String, HH:MM	Start time. An event with no start/end times is treated as all-day.
end-date	String, YYYY-MM-DD	End date. Defaults to the start date when omitted.
end-time	String, HH:MM	End time.
time-zone	String, default GMT	Event time zone. currentBrowser uses the browser time zone.
use-user-tz	Boolean, default false	Converts the event time and time zone to the visitor’s time zone.
location	String	Event location or online-event URL.
status	tentative, confirmed, cancelled; default confirmed	iCalendar event status.
sequence	Number, default 0	Positive event revision sequence.
availability	busy or free	Overrides calendar availability where the destination service honors it.
uid	String	Unique ICS event ID. A random value is generated when omitted.
organizer	String, NAME|EMAIL	Organizer data for rich event data and generated ICS files.
attendee	String, NAME|EMAIL or email	One attendee for event update workflows. An organizer is required when this option is used.
dates	Array of objects	Defines a multi-date event series. Root-level values override matching values inside date entries, with documented exceptions for series names and UIDs.
recurrence	RRULE string or daily, weekly, monthly, yearly	Defines recurrence. Multi-date mode and recurrence cannot be used together. Recurrence can remove Yahoo, Microsoft, and Google-on-iOS destinations when those services cannot process the rule; iCal becomes the fallback when necessary.
recurrence-interval	Number, default 1	Interval between recurrence iterations.
recurrence-until	String, UTC timestamp	Sets an end date for recurrence.
recurrence-count	Number	Maximum number of recurrence instances.
recurrence-by-day	String	Weekday rule such as MO, WE,FR, or 3MO.
recurrence-by-month-day	String	Numbered monthly date rule.
recurrence-by-month	String, 1-12	Month rule for yearly recurrence.
recurrence-weekstart	Weekday code, default MO	First weekday used by the recurrence rule.
subscribe	Boolean, default false	Changes the button from a single event to a hosted calendar subscription. Set ics-file; name and start-date are retained for the subscription setup. Microsoft Teams and Yahoo are disabled for subscriptions.
ics-file	String URL	Uses an existing ICS file or hosted calendar and skips dynamic ICS generation.
ical-file-name	String, default event-to-save-in-my-calendar	File name used for generated ICS downloads.

ICS file parameters

These attributes affect generated Apple/iCal files.

Attribute	Type / Values	Description
ics-reminder	String or number	Reminder time in minutes before the event or an ISO 8601 duration.
ics-url	String URL	Canonical event URL.
ics-categories	String or array	ICS event categories.
ics-class	public, private, confidential	ICS event classification.
ics-priority	Number 0-9	ICS priority value.
ics-geo	latitude,longitude	Geographic coordinates for the event.
ics-attach	String or array	One or more HTTP(S) attachment URLs.
ics-exdate	String or array, YYYY-MM-DD	Dates excluded from a recurring event. This option is root-only.
ics-created	UTC timestamp	Static ICS creation timestamp. The generated-file time is used by default.
ics-updated	UTC timestamp	Static ICS update timestamp. The generated-file time is used by default.

Layout and style parameters

Attribute	Type / Default	Description
options	Array	Calendar destinations: apple, google, ical, ms365, msteams, outlookcom, yahoo.
options-mobile	Array	Calendar destinations used on Android and other mobile devices.
options-ios	Array	Calendar destinations used on iOS.
button-style	String, default default	default, simple, 3d, flat, round, neumorphism, text, date, custom, or none.
inline	Boolean, default false	Uses inline rendering for the button container.
custom-css	String URL	External stylesheet used with button-style="custom". Custom CSS is not loaded during SSR.
style-source	String URL	Base URL for lazily loaded styles and locale assets in self-hosted browser builds.
load-all-styles	Boolean, default false	Prefetches all button style deltas for runtime style switching in script-tag integrations.
buttons-list	Boolean, default false	Renders one button per calendar destination.
label	String, default Add to Calendar	Main button text.
trigger	hover or click; default hover	Interaction that opens the calendar list.
list-style	String, default dropdown	dropdown, dropdown-static, dropup-static, overlay, or modal.
force-overlay	Boolean, default false	Renders the dropdown and button above the surrounding layout.
hide-background	Boolean, default false	Removes the list or modal background treatment.
hide-icon-button	Boolean, default false	Hides the main button icon.
hide-icon-list	Boolean, default false	Hides calendar list icons.
hide-icon-modal	Boolean, default false	Hides the info modal heading icon.
hide-text-label-button	Boolean, default false	Hides the main button text.
hide-text-label-list	Boolean, default false	Hides calendar list text.
hide-checkmark	Boolean, default false	Disables the saved-event checkmark where that indicator is active.
past-date-handling	none, disable, hide; default none	Controls non-recurring events after their date has passed.
size	String, default 6|6|6	Scale from 0 to 10, with optional large, medium, and small breakpoint values.
light-mode	system, dark, light, bodyScheme; default light	Color mode selection.
language	String, default en	Built-in locale codes: ar, az, be, bg, bs, cs, da, de, el, en, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, ko, lt, lv, mk, mt, nl, no, pl, pt, ro, ru, sk, sl, sq, sr, sv, tr, uk, vi, zh. Regional locale forms such as en_GB are accepted.
custom-labels	Object	Overrides built-in text labels.
style-light	String	CSS custom property overrides for the default/light scheme.
style-dark	String	CSS custom property overrides for dark mode.

Additional parameters

Attribute	Type / Default	Description
images	Array	Image URLs used in generated Schema.org event data.
hide-rich-data	Boolean, default false	Disables generated Schema.org event data.
identifier	String	Custom unique identifier used in generated element and calendar-link IDs.
bypass-web-view-check	Boolean, default false	Bypasses the iOS WebView workaround when the host app already handles ICS downloads correctly.
hide-branding	Boolean, default false	Hides the project branding.
cspnonce	String	Nonce value applied to inline style and script tags for Content Security Policy setups.
instance	Number	Increment this value to force the custom element to re-render.
pro-override	Boolean, default false	Lets local settings override matching Add to Calendar PRO settings.
debug	Boolean, default false	Reports configuration errors in the console and renders an error state.

PRO-only parameters

Attribute	Type	Description
prokey	String	Connects the element to an event managed through Add to Calendar PRO.
group-overview	Boolean	Shows a configured PRO event group as an event list.
group-overview-config	Object	Configures group layout and filtering through years-only, type, from, to, no-details, no-add, custom-domain, and add-via-list.

JavaScript API

Function	Description
atcb_action(config, triggerElement?)	Opens calendar actions from a custom element or programmatic trigger.
atcb_register_locale(lang, strings)	Registers a locale at runtime.
atcb_register_style(name, css)	Registers a button style at runtime.
atcb_generate_ty(...)	Public helper exported from the main package for PRO thank-you output.
atcb_generate_timestring(...)	Formats decorated event dates into localized time strings.
atcb_decorate_data_dates(...)	Normalizes and decorates event date data.

Public TypeScript types

Type	Description
ATCBActionEventConfig	Configuration type used by the imperative action API.
AddToCalendarButtonType	Public component configuration type.
EventDate	Event date entry type used by date-based configuration.
CustomLabelsObjectType	Type for custom label overrides.
GroupOverviewConfig	Type for PRO group overview configuration.
ATCBLanguage	Public locale type.

Server-side and worker entries

v3 includes dedicated exports for server-side rendering and DOM-free date utilities.

import { atcb_generate_ssr_html } from 'add-to-calendar-button/ssr';

import {
  atcb_decorate_data_dates,
  atcb_generate_timestring
} from 'add-to-calendar-button/utils';

Tracking events

Each component exposes its last interaction through atcb-last-event and pushes interaction records to the browser data layer.

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

Styling with CSS ::part

The component uses Shadow DOM. Use style-light/style-dark, a custom stylesheet, or these public ::part names for direct CSS styling:

• 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#event-button::part(atcb-button) {
  background: #222;
  color: #fff;
}

Important v2 to v3 migration notes

• Change the browser CDN URL from @2 to @3.
• Use official kebab-case HTML attributes such as start-date and button-style. JavaScript configuration objects use camelCase.
• Use lowercase calendar option values: apple, google, ical, ms365, msteams, outlookcom, and yahoo.
• Use lowercase event status values: tentative, confirmed, and cancelled.
• Rename v2 created/updated to HTML ics-created/ics-updated or JavaScript icsCreated/icsUpdated. The old timestamp names are not read in v3.
• npm projects need explicit imports for non-default styles and non-English locales.
• Update renamed custom-labels keys when your integration overrides date.status.cancelled.cta, label.share.email.subject, label.rsvp, form.status, or form.success.
• Review configured URLs. v3 rejects script-capable schemes such as javascript: and accepts only the documented URL schemes for calendar files, CSS, images, and event links.
• Legacy no-pro, unstyle, and no-pro-unstyle entries are compatibility shims. New code should use the main package entry.
• Full v3 behavior uses the Baseline 2023 browser floor, including Safari 16.4 and current evergreen browsers.

Alternatives and related resources

• calendar-link generates calendar URLs and ICS output from JavaScript event objects when a prebuilt button component is not required.
• Calendar.js is a full event calendar UI for displaying and managing events inside the page.

Changelog

v3.0.1

• Current v3 release used by the project documentation.
• v3 standardizes the HTML API on kebab-case attributes and lowercase calendar/status values.
• Dedicated SSR and DOM-free utility entries are available.
• Non-default npm styles and locales use explicit imports.
• New ICS-specific configuration is available for reminders, URLs, categories, classification, priority, geo data, attachments, excluded recurrence dates, and timestamps.

v2.15.0

• Final v2 series used by the previous CSSScript article.

The post Add to Calendar Button – JavaScript Calendar Links appeared first on CSS Script.