Utilisation avancée

1. Utiliser votre propre style CSS

Options intégrées

Cela semble évident, mais certains se lancent directement dans les solutions complexes alors que les fonctions intégrées et simples offrent déjà beaucoup de possibilités.

Consultez la page « Configuration » pour découvrir tous les réglages et toutes les fonctionnalités.

Les exemples suivants en utilisent quelques-uns pour illustrer la variété des styles inclus.

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  options="'apple','google','ical'"
  button-style="round"
  hide-icon-button
  hide-background
  label="Mon libellé personnalisé"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  options="'apple','google','ical'"
  button-style="flat"
  hide-icon-list
  buttons-list
  hide-background
  label="Plat et direct"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

<add-to-calendar-button
  name="Mon événement génial"
  start-date="2026-10-18"
  options="'apple','google','ical'"
  start-time="10:10"
  end-time="10:40"
  time-zone="Europe/Paris"
  location="Fantasy Marketplace"
  button-style="date"
  size="5"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

Remplacer les styles

Il n’est généralement pas possible de remplacer directement le style CSS, car le bouton se trouve dans son propre Shadow DOM.
Vous pouvez toutefois remplacer certaines variables CSS liées à l’hôte (= la balise <add-to-calendar-button>).
Fournissez les valeurs par défaut avec l’attribut « styleLight » et les valeurs du mode sombre avec « styleDark ».

Les variables disponibles dépendent du style choisi. Consultez le fichier CSS correspondant dans le dépôt ↗ (section « Global colors and shadows »).

Cela ne fonctionne pas avec le style de bouton « none » ni avec l’approche atcb_action (voir le nº 10).

<add-to-calendar-button
  style-light="--btn-background: #2f4377; --btn-text: #fff; --font: Georgia, 'Times New Roman', Times, serif;"
  style-dark="--btn-background: #000;"
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  options="'apple','google','ical'"
  hide-icon-button
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

Charger un fichier CSS externe

Vous pouvez aussi charger un fichier CSS externe. Indiquez-le avec l’option « customCss » et choisissez le style de bouton « custom ».
Ce fichier peut se trouver dans votre application, mais ne doit pas être regroupé avec d’autres feuilles CSS. Pour des raisons de sécurité, les chemins contenant « ../ » sont interdits. Une URL absolue est recommandée.

Dans ce cas, vous devez prendre en charge tous (!) les éléments.
Il est recommandé de copier une feuille de style fournie depuis le dépôt ↗, puis de la modifier.

Vérifiez aussi que votre système autorise le chargement de feuilles de style externes (aucune règle Content-Security-Policy bloquante, par exemple).

Dans cet exemple, nous restons simples et ne changeons que la couleur.

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  options="'apple','google','ical'"
  light-mode="bodyScheme"
  custom-css="https://add-to-calendar-button.com/atcb.css"
  button-style="custom"
  list-style="modal"
  language="fr"
></add-to-calendar-button>

Cibler des éléments avec ::part

Le sélecteur CSS ::part ↗ permet de styler directement des éléments présélectionnés depuis votre CSS habituel.
Les fenêtres modales (et donc le bouton avec « forceOverlay ») sont rendues dans un nouvel élément DOM : utilisez alors le sélecteur général « .add-to-calendar » ou « #atcb-btn-identifiantDuBouton-modal-host ».

Les éléments suivants sont disponibles :

• 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
  id="css-part-example"
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  options="'apple','google','ical'"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

<style>
  add-to-calendar-button#css-part-example::part(atcb-button),
  #atcb-btn-css-part-example-modal-host::part(atcb-button),
  #css-part-example::part(atcb-list),
  #atcb-btn-css-part-example-modal-host::part(atcb-list) {
    background-color: #264f3c;
    color: #fff;
  }
  /* or, for all buttons and modals:
  .add-to-calendar::part(atcb-button) {
    background-color: #264f3c;
    color: #fff;
  }
  */
</style>

Utiliser un objet personnalisé comme bouton

Enfin, vous pouvez conserver un style fourni tout en utilisant votre propre élément déclencheur.
Consultez l’exemple « 10. Utiliser votre propre bouton » au bas de cette page.

2. Enrichir la description de l’événement

La description de l’événement ne doit pas nécessairement être du texte brut !
Vous pouvez utiliser des caractères HTML spéciaux et des règles de mise en forme.

Ces règles prennent la forme de pseudo-balises HTML transformées automatiquement.
(Dans le shortcode de l’extension WordPress, « ] » casserait le code. Vous pouvez utiliser {*} au lieu de [*].)
(Apple, Yahoo et Microsoft Teams ne sont pas entièrement compatibles : le contenu est converti en texte brut avec uniquement les sauts de ligne et les liens.)

Balises prises en charge:

• [hr]
• [p] ... [/p]
• [br]
• [strong] ... [/strong]
• [u] ... [/u]
• [i] ... [/i], [em] ... [/em]
• [ul] ... [/ul], [ol] ... [/ol], [li] ... [/li]
• [h*] ... [/h*] (← h1, h2, h3, ...)
• [url] ... [/url]
  Définissez le texte du lien ainsi : [url]https://....|Texte du lien[/url]

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  start-time="10:15"
  end-time="23:30"
  time-zone="Europe/Paris"
  options="'apple','google','ical','outlookcom','ms365','msteams','yahoo'"
  light-mode="bodyScheme"
  description="[p][strong]Découvrez[/strong] la façon peut-être [u]la plus simple[/u] d’intégrer des boutons Add to Calendar à votre site ! 🚀[/p][p]💻 [em]Visitez le site officiel pour plus d’inspiration :[/em][br]&rarr; [url]https://add-to-calendar-button.com/fr/|Cliquez ici ![/url][/p]"
  language="fr"
></add-to-calendar-button>

3. Proposer un abonnement à un calendrier

Vous pouvez proposer à vos utilisateurs de s’abonner à un calendrier au lieu d’enregistrer uniquement des événements statiques.

Pour cela, définissez l’adresse publique du calendrier (un fichier .ics) dans l’option « icsFile » et activez l’option « subscribe ».

« name » reste obligatoire, mais tous les autres paramètres d’événement peuvent être omis.
Pour les services Microsoft, « name » sert de nom au calendrier.
Aucune donnée enrichie n’est générée pour un abonnement. Microsoft Teams n’est pas encore pris en charge et Yahoo ne l’est plus ; tous deux sont désactivés automatiquement. Il en va de même pour les autres services Microsoft sur mobile.
L’application Google Calendar sur Android ne prend en charge que les abonnements Google Calendar. Les autres URL sont ouvertes dans Chrome.
(Si le navigateur ne détecte aucune application de calendrier installée, un écran vide peut apparaître. La version PRO atténue ce problème avec un écran intermédiaire explicatif.)

<add-to-calendar-button
  name="[Abonnement test] Add to Calendar Button"
  subscribe
  ics-file="https://add2cal.github.io/ics-demo/demo-calendar.ics"
  options="'apple','google','ical','outlookcom','ms365','msteams','yahoo'"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

4. Texte personnalisé

Vous pouvez modifier tous les blocs de texte.

Pour le libellé du bouton, utilisez simplement l’option « label ».

Pour les autres textes (comme « Fermer » dans une liste modale), utilisez « customLabels ».
Fournissez une structure JSON et définissez les textes à remplacer.
Consultez le fichier atcb-i18n.js ↗ du dépôt pour connaître les clés disponibles.
Un libellé personnalisé remplace toujours la traduction.

(Si vous souhaitez seulement traduire les libellés, utilisez plutôt l’option « language » !)

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  start-time="10:15"
  end-time="23:30"
  label="Cliquez pour enregistrer !"
  options="'apple','google','ical','outlookcom','yahoo'"
  list-style="modal"
  customLabels='{"close":"Fermer la liste","apple":"Apple me convient","google":"Ajouter à Google Agenda","outlookcom":"Utiliser plutôt Outlook","yahoo":"Yahoo, vraiment ?","ical":"iCal pour gagner !"}'
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

5. Utiliser les propriétés iCal avancées

Si les réglages iCal inhabituels ne vous effraient pas, utilisez les options « uid », « sequence », « ics-created », « ics-updated », « attendee » et « status » (tentative, confirmed, cancelled).
Elles remplacent les valeurs par défaut correspondantes.

Ces options ne sont prises en charge que par les liens iCal et Apple Calendar !

Pour mettre à jour un événement existant (par exemple son statut), augmentez « sequence », utilisez une date « ics-updated » plus récente, conservez les mêmes « ics-created » et « uid », et fournissez l’organisateur (nom et adresse e-mail).

Certains calendriers exigent aussi « attendee ». Si la mise à jour n’est pas un changement de statut vers « cancelled », ce champ est toujours obligatoire !
L’attendee doit être la personne qui enregistre l’événement. N’utilisez cette fonctionnalité que si vous connaissez cette information.

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  start-time="10:15"
  end-time="23:30"
  time-zone="Europe/Paris"
  label="Ajouter l’événement"
  description="Un exemple assez particulier pour personnaliser Add to Calendar Button au maximum.[br]En savoir plus sur [url]https://add-to-calendar-button.com/fr/[/url]"
  options="ical"
  organizer="Jean Dupont|jean.dupont@mail.com"
  uid="7060df05-7b3d-4baa-b215-689b85769e5b"
  sequence="1"
  ics-created="20221201T103000Z"
  ics-updated="20221205T154500Z"
  status="confirmed"
  ical-file-name="Evenement-confirme"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  start-time="10:15"
  end-time="23:30"
  time-zone="Europe/Paris"
  label="Annuler l’événement"
  description="Un exemple assez particulier pour personnaliser Add to Calendar Button au maximum.[br]En savoir plus sur [url]https://add-to-calendar-button.com/fr/[/url]"
  options="ical"
  organizer="Jean Dupont|jean.dupont@mail.com"
  uid="7060df05-7b3d-4baa-b215-689b85769e5b"
  sequence="2"
  ics-created="20221201T103000Z"
  ics-updated="20221218T154500Z"
  status="cancelled"
  ical-file-name="Evenement-annule"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

6. Définir un identifiant personnalisé

Un identifiant est attribué à chaque bouton généré selon le modèle « atcb-btn-X », où « X » est un nombre croissant.
Chaque lien de calendrier reçoit ensuite l’identifiant du bouton suivi du type de calendrier, par exemple « atcb-btn-5-google ».

Vous pouvez remplacer le « X » automatique par une valeur distincte avec l’option « identifier ».
Cela peut permettre un suivi plus précis des interactions.

Cet identifiant doit être unique et ne doit être utilisé par aucun autre élément !

Avec la fonction personnalisée atcb_action, le script peut d’abord utiliser l’identifiant de l’élément déclencheur avant de revenir au modèle décrit.

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  start-time="10:15"
  end-time="23:30"
  time-zone="Europe/Paris"
  options="'apple','google','ical','outlookcom','ms365','msteams','yahoo'"
  identifier="my-custom-id"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

7. Suivi

Nous suivons chaque action effectuée avec un bouton.
Vous pouvez lire ces données de deux façons.

1. Observez l’attribut atcb-last-event ajouté à chaque bouton. Il contient le dernier événement et son déclencheur (modèle : « EVENT:TRIGGER » ; exemple : « openList:atcb-btn-1 »).
2. Accédez au Data Layer.

Nous envoyons directement les événements dans le Data Layer, lisible notamment par Google Tag Manager et Google Analytics.

Événements disponibles:

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

(Essayez en manipulant un bouton de ce site, puis en saisissant « dataLayer » dans la console JavaScript.)

8. Utiliser le fuseau horaire du navigateur

Dans de rares cas, l’événement n’est pas lié à un lieu et une heure précis, mais à une heure dans le fuseau propre à chaque utilisateur.
Par exemple, un rappel demandant à chacun de se brosser les dents à 8 h.

Dans ce cas, définissez l’option « timeZone » sur « currentBrowser ».
L’heure de l’événement sera automatiquement adaptée au fuseau de chaque utilisateur.

<add-to-calendar-button
  name="[Rappel] Tester Add to Calendar Button"
  start-date="2026-10-18"
  start-time="10:00"
  end-time="11:00"
  time-zone="currentBrowser"
  location="World Wide Web"
  description="Découvrez la façon peut-être la plus simple d’intégrer des boutons Add to Calendar dans vos projets web :[br]→ [url]https://add-to-calendar-button.com/fr/|Cliquez ici ![/url]"
  options="'apple','google','ical'"
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

9. WebView

Sur mobile, les applications utilisant une « WebView » rencontrent des problèmes avec la génération et la livraison à la volée des fichiers .ics.
Nous détectons ces cas, copions l’URL de données dans le presse-papiers et affichons un bref guide.

Cette bonne pratique convient aux sites et applications web, mais pas forcément à votre propre application native ou hybride, où vous contrôlez les réglages de la WebView.

La génération dynamique du fichier .ics resterait impossible, mais vous pourriez livrer directement un fichier ICS externe existant.
Désactivez alors ce contournement avec l’option « bypassWebViewCheck ».

Vérifiez que les conditions suivantes s’appliquent à votre projet !

• Vous développez votre propre application native ou hybride.
• Vous ouvrez le navigateur par défaut de l’appareil au lieu d’utiliser une WebView intégrée.
• Vous disposez d’un fichier .ics distinct sur un serveur et pouvez le référencer avec l’option « icsFile ».

(Le bouton ci-dessous ne devrait pas fonctionner dans une WebView intégrée comme celle de l’application Instagram, mais fonctionnerait dans votre application.)

<add-to-calendar-button
  name="Titre"
  start-date="2026-10-18"
  start-time="10:15"
  end-time="23:30"
  options="ical"
  ics-file="https://add-to-calendar-button.com/demo-event.ics"
  bypass-web-view-check
  light-mode="bodyScheme"
  language="fr"
></add-to-calendar-button>

10. Utiliser votre propre bouton

Pour ceux qui veulent une personnalisation complètement débridée, nous permettons aussi de déclencher manuellement la liste des liens de calendrier.
Vous pouvez ainsi utiliser n’importe quel élément comme bouton, voire déclencher l’action par programmation.

En théorie, aucun bouton n’est nécessaire. Il reste fortement recommandé, car il améliore nettement l’expérience (retour du focus à la fermeture de la fenêtre modale, etc.).
Sans bouton, la liste s’affiche automatiquement dans une fenêtre modale. Avec un bouton, vous pouvez choisir la liste déroulante superposée via « listStyle » (les autres options ne sont pas prises en charge avec atcb_action). Le style modal est vivement recommandé.

Remarque : sur un appareil Apple, si seule l’option Apple ou iCal est configurée, une fenêtre intermédiaire apparaît avant l’enregistrement. Elle garantit l’ouverture et l’enregistrement fiables du fichier généré. Cette étape est ignorée lorsqu’un fichier ICS statique est fourni.

Étape 1 : import

Si vous utilisez le script via CDN, ignorez cette étape.
Avec le paquet npm, importez d’abord la fonction « atcb_action » comme suit :

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

Étape 2 : configuration et déclencheur

Définissez ensuite la configuration et le déclencheur.
L’implémentation peut varier fortement selon votre environnement : vous en êtes l’expert.

Pour la démonstration, l’exemple utilise un bouton très simple.

<button id="my-default-button">Cliquez ici</button>

<script type="application/javascript">
  const config = {
    name: "[Rappel] Tester Add to Calendar Button",
    description: "Découvrez la façon peut-être la plus simple d’intégrer des boutons Add to Calendar dans vos projets web :[br]→ [url]https://add-to-calendar-button.com/fr/|Cliquez ici ![/url]",
    startDate: "2026-10-18",
    startTime: "10:15",
    endTime: "23:30",
    options: ["google", "ical"],
    timeZone: "Europe/Paris",
    language: "fr"
  };
  const button = document.getElementById('my-default-button');
  if (button) {
    button.addEventListener('click', () => atcb_action(config, button));
  }
</script>

11. Stratégies de chargement

Avant tout :
Dès que possible, nous chargeons le script de façon asynchrone afin de ne pas bloquer le rendu de la page.
Le script est aussi fortement découpé : le bundle ne contient que le cœur, le style de bouton par défaut et l’anglais.
Chaque autre style (quelques Ko) et chaque autre langue (environ 3 Ko) est chargé automatiquement à la demande depuis la même origine que le script.

Vous n’avez généralement rien à faire. Mais vous pouvez garder le contrôle :

1. Lors du bundling, importez exactement ce que vous utilisez : aucune requête ne sera effectuée pour ces ressources :

import 'add-to-calendar-button'; // cœur + style par défaut + anglais
import 'add-to-calendar-button/styles/3d'; // les styles utilisés
import 'add-to-calendar-button/i18n/de'; // les langues proposées

Pour charger tous les styles ou toutes les langues en une fois, utilisez les modules agrégés : import 'add-to-calendar-button/styles/all' et import 'add-to-calendar-button/i18n/all'.

2. Avec la balise script, les ressources sont chargées depuis l’origine du script. Remplacez cet emplacement avec l’option styleSource si vous les hébergez ailleurs.
3. Si vous changez buttonStyle à l’exécution, activez loadAllStyles pour précharger toutes les différences.

12. Rendu côté serveur

Le bouton peut rendre une enveloppe sur le serveur.
L’entrée add-to-calendar-button/ssr produit avec le Shadow DOM déclaratif un espace réservé dont le style et la taille sont corrects : il s’affiche avant tout JavaScript, puis le script client le met à niveau sur place sans décalage de mise en page.

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

const html = atcb_generate_ssr_html({
  name: 'Launch Party',
  startDate: '2050-06-15',
  buttonStyle: '3d',
  language: 'de',
});
// insérez la chaîne renvoyée dans votre page rendue par le serveur

Dans votre entrée client, enregistrez tous les styles et toutes les langues autres que ceux par défaut avant de charger le module principal :

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

Pour les événements PRO, utilisez la fonction asynchrone atcb_generate_ssr_html_async. Elle récupère et fusionne la configuration hébergée du proKey avant de rendre l’enveloppe. Sans proKey, elle se comporte comme la fonction synchrone.

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

const html = await atcb_generate_ssr_html_async({
  proKey: 'YOUR_PRO_KEY',
});

L’enveloppe respecte le style, la taille, le mode clair, les langues de droite à gauche et le libellé (valeur localisée par défaut ou valeur de « label »). Lors de la première mise à niveau côté client, les nœuds de style correspondants restent en place, ce qui évite une image non stylée pendant l’hydratation.
Les boutons de style date, les RSVP en ligne et les aperçus de groupe affichent des squelettes discrets, car leur contenu nécessite une logique côté client. Tout le reste se produit à l’hydratation.

Les navigateurs sans prise en charge du Shadow DOM déclaratif ignorent simplement l’enveloppe et s’initialisent uniquement côté client : aucune gestion supplémentaire n’est nécessaire.