API

TwistCal's programmatic API — createButton, bindTrigger, autoInit, URL generators, ICS builder, addCalendar, and i18n functions.

Full control — generate URLs or ICS strings yourself, wire them to anything:

import {
  createButton,
  generateICS,
  googleUrl,
  outlookUrl,
  yahooUrl,
  downloadICS,
  detectLanguage,
  getTranslation,
  supportedLanguages
} from '@freshjuice/twistcal';

const event = {
  title: 'Coffee with the Team',
  start: '2026-01-20T11:00:00',
  end: '2026-01-20T11:45:00',
  location: 'Blue Bottle, 3rd St',
  description: 'Casual sync. No agenda.'
};

// Mount a full dropdown button
createButton(document.getElementById('mount'), event);

// Get a deep link URL string
const url = googleUrl(event);    // → "https://calendar.google.com/calendar/render?..."
window.open(url, '_blank', 'noopener');

// Generate .ics string
const ics = generateICS(event);  // → "BEGIN:VCALENDAR\r\n..."

// Or download .ics directly
downloadICS(event);

Exports

Export	Signature	Returns
`createButton`	`(target: HTMLElement, event: object) => HTMLElement`	Mounted `<twist-cal>` element
`bindTrigger`	`(el: HTMLElement, action: string, event?: object) => void`	Click handler bound
`autoInit`	`(scope?: HTMLElement \| Document) => void`	Wires all `[data-twistcal]` in scope
`addCalendar`	`(id: string, label: string, icon?: string, urlFn: (event) => string) => void`	Registers a custom calendar service
`generateICS`	`(event: object) => string \| null`	RFC 5545 ICS string
`googleUrl`	`(event: object) => string \| null`	Google Calendar compose URL
`outlookUrl`	`(event: object) => string \| null`	Outlook compose URL
`yahooUrl`	`(event: object) => string \| null`	Yahoo Calendar compose URL
`downloadICS`	`(event: object) => void`	Triggers `.ics` file download
`detectLanguage`	`(configLang?: string) => string`	Auto-detect language code
`getTranslation`	`(lang: string) => object`	Translation for a language
`supportedLanguages`	`string[]`	List of supported language codes

`createButton`

Mounts a <twist-cal> element on a target and returns it. Pass any attributes the web component accepts:

import { createButton } from '@freshjuice/twistcal';

const el = createButton(document.getElementById('mount'), {
  title: 'Team Sync',
  start: '2026-01-15T10:00:00',
  end: '2026-01-15T11:00:00',
  variant: 'outline',
  calendars: 'google,ics'
});

`bindTrigger`

Bind a click handler to an element, making it a calendar trigger. Skips attribute parsing — pass the event object directly:

import { bindTrigger } from '@freshjuice/twistcal';

bindTrigger(document.getElementById('my-btn'), 'google', {
  title: 'Team Sync',
  start: '2026-01-15T10:00:00',
  end: '2026-01-15T11:00:00'
});

`autoInit`

Wires all [data-twistcal] elements in a scope. Runs automatically on DOMContentLoaded; call it manually for dynamically injected content:

import { autoInit } from '@freshjuice/twistcal';

autoInit();                              // whole document
autoInit(document.getElementById('new')); // a container

Generators

Import just the URL/ICS logic — no web component, no icons, no i18n. 3 KB:

import { generateICS, googleUrl, outlookUrl, yahooUrl } from '@freshjuice/twistcal/generators';

Slim import

Drop the icons (~8 KB) if you don’t need them:

import { createButton } from '@freshjuice/twistcal/slim';

`addCalendar`

Register a custom calendar service. It then appears in the dropdown (via calendars="mycal") and works with bindTrigger(el, 'mycal', event):

import { addCalendar } from '@freshjuice/twistcal';

addCalendar('mycal', 'My Calendar', '<svg>...</svg>', (event) => {
  return `https://mycal.example.com/add?title=${encodeURIComponent(event.title)}`;
});

<twist-cal calendars="google,mycal" title="..." start="..." end="...">
</twist-cal>

i18n functions

See Internationalization for the full language list and auto-detection priority.

import { detectLanguage, getTranslation, supportedLanguages } from '@freshjuice/twistcal';

detectLanguage('de');          // → 'de' (explicit wins)
detectLanguage();              // → auto-detected from <html lang> / navigator.language
getTranslation('fr');          // → { label: 'Ajouter au calendrier', services: { ... } }
supportedLanguages;            // → ['en', 'de', 'es', 'fr', 'it', 'pt', 'nl', 'pl', 'uk', 'ru', 'ja', 'zh']

Web component — all attributes
Internationalization — 12 languages
Datetime — timezone handling

MenuUser Preferences

API