---
title: "API"
url: "https://twistcal.com/docs/api"
description: "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](/docs/i18n/) 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']
```

## Next

-   [Web component](/docs/web-component/) — all attributes
-   [Internationalization](/docs/i18n/) — 12 languages
-   [Datetime](/docs/datetime/) — timezone handling