Advanced Options

For power users who want full control over the calendar widget beyond what the dashboard and query parameters offer.

CSS custom property overrides

You can override any visual property by adding extra keys to the theme JSON object in the embed URL. Any key beyond the fixed theme keys (layout, palette, orientation, imagePosition) is converted to a CSS custom property.

The conversion follows a camelCase to --already-kebab-case pattern:

For example, to use a custom brand color and font on top of the light palette:

<iframe
  src="https://embed.already.events/v/my-view?theme=%7B%22palette%22%3A%22light%22%2C%22primary%22%3A%22%232563eb%22%2C%22fontFamily%22%3A%22Georgia%2C%20serif%22%7D"
  style="width: 100%; height: 600px; border: none;"
  title="Event Calendar"
></iframe>

The theme parameter above decodes to:

{
  "palette": "light",
  "primary": "#2563eb",
  "fontFamily": "Georgia, serif"
}

See Palettes for the full list of overridable properties.

Sticky header options

The sticky header can be configured granularly as an object instead of a simple boolean:

{
  "header": true,
  "viewSelector": true,
  "tagFilter": false
}

Each key controls whether that UI element sticks to the top of the viewport as the visitor scrolls. Set sticky to this object in the embed URL to pin specific elements while letting others scroll.

Extending known platforms

The calendar recognizes URLs from 18+ platforms by default. If you're using the JavaScript API directly (not the iframe embed), you can extend the platform list using Already.DEFAULTS:

Already.init({
  el: '#calendar',
  google: { apiKey: '...', calendarId: '...' },
  knownPlatforms: [
    ...Already.DEFAULTS.knownPlatforms,
    { pattern: /your-site\.com/i, label: 'Visit Our Site' },
  ],
});

Already.DEFAULTS contains all the default configuration values. Spreading it into your config lets you extend rather than replace the built-in platform list.

Callbacks

When using the JavaScript API, you can register callback functions for event-driven behavior:

• onEventClick(event, viewName) — called when a visitor clicks an event. Return false to prevent navigation to the detail view.
• onViewChange(newView, oldView) — called when the active view changes.
• onDataLoad(data) — called after events load successfully.
• onError(error) — called if event loading fails.

Data hooks

Transform or filter events before they're displayed:

• eventTransform(event) — modify each event after enrichment (add fields, change values). Return the modified event.
• eventFilter(event) — return true to keep the event, false to exclude it.

These hooks run in the pipeline after built-in enrichment (directive extraction, image detection, etc.) and before rendering.