Datetime & timezones

Pass datetimes in ISO 8601. With a timezone offset (2026-02-10T14:00:00Z or 2026-02-10T14:00:00-05:00) the calendar services get an absolute time. Without one (2026-02-10T14:00:00) the browser treats it as local time and converts to UTC — usually what you want for a page visited from multiple time zones.

Timezone

When the event happens in a specific timezone (not the visitor’s), pass the IANA name:

<twist-cal
  title="Oslo Team Sync"
  start="2026-01-15T10:00:00"
  end="2026-01-15T11:00:00"
  timezone="Europe/Oslo">
</twist-cal>

A visitor in Miami clicks the button — their Google Calendar gets 20260115T090000Z (09:00 UTC = 10:00 Oslo = 04:00 Miami). DST is handled via Intl.DateTimeFormat, so the offset is correct for the event’s date, not the visitor’s current date.

IANA timezone examples

Zone	Example
Europe/Oslo	CET/CEST, +1/+2
America/New_York	EST/EDT, -5/-4
Asia/Tokyo	JST, +9 (no DST)
Australia/Sydney	AEDT/AEST, +11/+10
Pacific/Honolulu	HST, -10 (no DST)

Full list: any IANA timezone database name works.

Explicit offsets win

If start/end already carry an offset (Z or +05:00), the timezone attribute is ignored — the explicit offset wins:

<!-- timezone ignored — offset is in the string -->
<twist-cal
  title="Fixed UTC event"
  start="2026-01-15T10:00:00Z"
  end="2026-01-15T11:00:00Z"
  timezone="Europe/Oslo">
</twist-cal>

All-day events

Set all-day="true" for date-only formats. Pass dates, not datetimes:

<twist-cal
  all-day="true"
  title="Company offsite"
  start="2026-04-20"
  end="2026-04-22">
</twist-cal>

Produces date-only .ics (VALUE:DATE) and Google/Yahoo all-day URLs. timezone is irrelevant for all-day events.

Programmatic timezone handling

The generators export helpers for advanced use:

import { parseInTz, tzOffsetMs, normalizeEvent } from '@freshjuice/twistcal/generators';

// Parse a naive datetime as wall-clock in a timezone → UTC Date
parseInTz('2026-01-15T10:00:00', 'Europe/Oslo');  // → 2026-01-15T09:00:00Z (winter)

// Get UTC offset (ms) for a timezone at a UTC instant
tzOffsetMs('Europe/Oslo', Date.parse('2026-01-15T00:00:00Z'));  // → 3600000 (+1h)

// Normalize an event: convert naive start/end to UTC if timezone is set
normalizeEvent({ ...event, timezone: 'Europe/Oslo' });

See the API for the full export list.

Next

• Web component — the timezone attribute
• API — generator helpers